PCL
pcl::MetaProcess Class Referenceabstract

A formal description of a PixInsight process. More...

#include <MetaProcess.h>

+ Inheritance diagram for pcl::MetaProcess:

Public Member Functions

 MetaProcess ()
 
 MetaProcess (const MetaProcess &)=delete
 
 MetaProcess (MetaProcess &&x)=delete
 
virtual ~MetaProcess () noexcept(false)
 
virtual IsoString Aliases () const
 
bool BrowseDocumentation () const override
 
bool CanBrowseDocumentation () const override
 
bool CanEditPreferences () const override
 
bool CanProcessCommandLines () const override
 
bool CanProcessGlobal () const override
 
bool CanProcessImages () const override
 
virtual bool CanProcessIPCMessages () const
 
bool CanProcessViews () const override
 
virtual IsoString Categories () const
 
virtual IsoString Category () const
 
virtual ProcessImplementationClone (const ProcessImplementation &) const =0
 
virtual ProcessImplementationCreate () const =0
 
virtual ProcessInterfaceDefaultInterface () const
 
String Description () const override
 
bool EditPreferences () const override
 
Bitmap Icon () const override
 
virtual String IconImageFile () const
 
virtual IsoString IconImageSVG () const
 
virtual String IconImageSVGFile () const
 
virtual const char ** IconImageXPM () const
 
virtual IsoString Id () const override=0
 
virtual void InitializeClass ()
 
virtual void IPCSetParameters (int instance, const IsoString &messageUID, const String &parameters) const
 
virtual void IPCStart (int instance, const IsoString &messageUID, const String &parameters) const
 
virtual int IPCStatus (int instance, const IsoString &messageUID) const
 
virtual void IPCStop (int instance, const IsoString &messageUID) const
 
bool IsAssignable () const override
 
bool NeedsInitialization () const override
 
bool NeedsValidation () const override
 
MetaProcessoperator= (const MetaProcess &)=delete
 
MetaProcessoperator= (MetaProcess &&x)=delete
 
const MetaParameteroperator[] (size_type i) const
 
bool PrefersGlobalExecution () const override
 
virtual int ProcessCommandLine (const StringList &argv) const
 
String ScriptComment () const override
 
Bitmap SmallIcon () const override
 
virtual String SmallIconImageFile () const
 
virtual const char ** SmallIconImageXPM () const
 
virtual ProcessImplementationTestClone (const ProcessImplementation &p) const
 
uint32 Version () const override
 
- Public Member Functions inherited from pcl::MetaObject
 MetaObject (MetaObject *parent)
 
 MetaObject (const MetaObject &)=delete
 
 MetaObject (MetaObject &&x)=delete
 
virtual ~MetaObject () noexcept(false)
 
size_type Length () const
 
MetaObjectoperator= (const MetaObject &)=delete
 
MetaObjectoperator= (MetaObject &&x)=delete
 
const MetaObjectoperator[] (size_type i) const
 
const MetaObjectParent () const
 
MetaObjectParent ()
 
- Public Member Functions inherited from pcl::ProcessBase
 ProcessBase ()
 
virtual ~ProcessBase () noexcept(false)
 

Additional Inherited Members

- Public Types inherited from pcl::MetaObject
typedef IndirectArray< MetaObjectchildren_list
 

Detailed Description

MetaProcess provides a formal description of the basic functionality and properties of a process in a PixInsight module.

In a PixInsight module, every process must be implemented as a derived class of MetaProcess. Such subclass will describe general properties of the process, and will provide the basic mechanisms to instantiate a process and generate duplicates of existing process instances.

MetaProcess and its subclasses don't implement any processing capabilities. The actual processing work must be implemented through a process instance implementation class, which is always a descendant of the ProcessImplementation class in the PixInsight/PCL framework.

Each process must have a unique identifier. Process identifiers are crucial for many key features of the PixInsight environment, like process scripting, command-line interfaces, process icons and containers, etc.

Processes are organized by process categories in PixInsight. A process category groups similar or related processes together. The whole set of process categories forms a categorized tree of processes that can be accessed, for example, from the Process Explorer window in the core PixInsight GUI.

See also
MetaModule, MetaParameter, ProcessImplementation

Definition at line 106 of file MetaProcess.h.

Constructor & Destructor Documentation

◆ MetaProcess() [1/3]

pcl::MetaProcess::MetaProcess ( )

Constructs a MetaProcess object.

◆ ~MetaProcess()

virtual pcl::MetaProcess::~MetaProcess ( )
inlinevirtualnoexcept

Destroys this MetaProcess object. Also destroys all MetaParameter children of this MetaProcess.

Definition at line 119 of file MetaProcess.h.

References pcl::ImageOp::Id().

◆ MetaProcess() [2/3]

pcl::MetaProcess::MetaProcess ( const MetaProcess )
delete

Copy constructor. Copy semantics are disabled for MetaProcess because this class represents unique server-side objects.

◆ MetaProcess() [3/3]

pcl::MetaProcess::MetaProcess ( MetaProcess &&  x)
delete

Move constructor. Move semantics are disabled for MetaProcess because because of parent-child server-side object relations.

Member Function Documentation

◆ Aliases()

virtual IsoString pcl::MetaProcess::Aliases ( ) const
inlinevirtual

Returns a list of alias identifiers for this process.

A process can have one or more alias identifiers. Aliases are useful to maintain compatibility with previous versions of a process.

When the PixInsight core application imports a process instance (e.g., from a process icon) it automatically replaces alias process identifiers with actual (current) identifiers. This allows a developer to change the identifier of a process without breaking compatibility with process instances in existing icon collections or projects.

The returned string is a comma-separated list of distinct identifiers that will be treated as synonyms to the actual identifier of this process, which is returned by the Id() member function. Two installed processes can't have the same alias, so each identifier included in the returned list must be unique among all installed processes on the entire PixInsight platform.

Note
The default implementation of this member function returns an empty string (no aliases).
See also
Id()

Definition at line 175 of file MetaProcess.h.

◆ BrowseDocumentation()

bool pcl::MetaProcess::BrowseDocumentation ( ) const
overridevirtual

Handles a request to browse documentation specific for this process. Returns true iff the documentation was loaded successfully.

Reimplementing this function is strongly discouraged, unless some nonstandard behavior is absolutely necessary for a particular process. Since version 1.7 of the PixInsight core application, the integrated documentation system works in a completely automatic and standardized way to provide documentation browsing and searching functionality.

The default implementation of this member function automatically launches and loads the integrated documentation browser with the documentation for this process, if it exists and has been installed. For more information, please read the documentation for the CanBrowseDocumentation() function.

Note
This function will never be called unless the CanBrowseDocumentation() member function is reimplemented to return true.
See also
CanBrowseDocumentation()

Implements pcl::ProcessBase.

◆ CanBrowseDocumentation()

bool pcl::MetaProcess::CanBrowseDocumentation ( ) const
inlineoverridevirtual

Returns true iff this process is able to open a documentation browser with specific documentation contents.

Starting from version 1.7, the PixInsight core application implements an integrated documentation system. The core application provides automatic documentation browsing and searching functionality. For this reason, the default implementation of this member function returns true.

Unless a process has specific documentation requirements beyond the integrated documentation system –which is strongly discouraged–, the BrowseDocumentation() member function of MetaProcess should not be reimplemented in derived classes. The default implementation drives the integrated documentation system automatically in a standardized way.

Note
The default implementation of this function returns true, for the same reasons explained above.
See also
BrowseDocumentation()

Implements pcl::ProcessBase.

Definition at line 679 of file MetaProcess.h.

◆ CanEditPreferences()

bool pcl::MetaProcess::CanEditPreferences ( ) const
inlineoverridevirtual

Returns true iff this process is able to edit specific preferences.

If a derived class reimplements this function to return true, it should also reimplement the EditPreferences() member function to perform the actual preferences edit work, or a runtime exception will be thrown.

Note
The default implementation of this function returns false, so by default processes can't edit specific preferences.
See also
EditPreferences()

Implements pcl::ProcessBase.

Definition at line 654 of file MetaProcess.h.

◆ CanProcessCommandLines()

bool pcl::MetaProcess::CanProcessCommandLines ( ) const
inlineoverridevirtual

Returns true iff this process class is able to process specific command-line invocations.

If a derived class reimplements this function to return true, it should also reimplement the ProcessCommandLine() member function to perform actual command line processing, or a runtime exception will be thrown.

Note
The default implementation of this function returns false, so by default processes can't process command-line arguments.
See also
ProcessCommandLine()

Implements pcl::ProcessBase.

Definition at line 637 of file MetaProcess.h.

◆ CanProcessGlobal()

bool pcl::MetaProcess::CanProcessGlobal ( ) const
inlineoverridevirtual

Returns true iff this process class can be executed globally.

Global execution of a process, also known as global context, is mainly implemented by the following member functions:

bool ProcessImplementation::CanExecuteGlobal( String& ) bool ProcessImplementation::ExecuteGlobal()

which must be reimplemented by any instance class corresponding to a process with global execution capabilities.

Note
For compatibility with previous PCL versions, the default implementation of this function returns true, so by default a process is supposed to be executable globally. There are not many global processes, and only a few processes can be executed in both the global and view contexts, so this default behavior is clearly suboptimal. However, as noted above it is necessary to maintain compatibility with 1.x PCL versions. This may change in a future version 2.x of PCL.

Implements pcl::ProcessBase.

Definition at line 586 of file MetaProcess.h.

◆ CanProcessImages()

bool pcl::MetaProcess::CanProcessImages ( ) const
inlineoverridevirtual

Returns true iff this process class is able to process standalone images.

This refers to the ability of process instances to be executed on images passed to a reimplementation of the following member function:

bool ProcessImplementation::ExecuteOn( ImageVariant&, const IsoString& )

Note that this is completely different from processing views with a reimplementation of:

bool ProcessImplementation::ExecuteOn( View& )

Although both functions usually share the majority of their working code for most processes, they are unrelated from the point of view of the PixInsight core application, and they also play very different roles for the integration of a process with the platform.

If a derived class reimplements this function to return true, the corresponding process instance implementation class should also reimplement the following ones:

bool ProcessImplementation::CanExecuteOn( const ImageVariant&, String& ) const bool ProcessImplementation::ExecuteOn( ImageVariant& )

Note
The default implementation of this function returns false, so by default a process has no standalone image processing capabilities.

Implements pcl::ProcessBase.

Definition at line 619 of file MetaProcess.h.

◆ CanProcessIPCMessages()

virtual bool pcl::MetaProcess::CanProcessIPCMessages ( ) const
inlinevirtual

Returns true iff this process can handle inter-process communication (IPC) messages send among running instances of the PixInsight core application.

The following IPC process messages are implemented in current versions of the PixInsight platform:

  • Start Process. Handled by a reimplementation of the IPCStart() member function in a derived class.
  • Stop Process. Handled by a reimplementation of the IPCStop() member function in a derived class.
  • Get Process Status. Handled by a reimplementation of the IPCStatus() member function in a derived class.

Process execution controlled by IPC messages is primarily intended for automation of non-interactive or unattended tasks. A good example is the NetworkService process, which can be controlled with IPC messages to implement generic, asynchronous online services without user interaction.

The default implementation of this member function returns false. This means that IPC messages are not supported by default. To support them, this member function must be reimplemented in a derived class to return true, along with IPCStart(), IPCStop(), IPCSetParameters() and IPCStatus().

Definition at line 927 of file MetaProcess.h.

◆ CanProcessViews()

bool pcl::MetaProcess::CanProcessViews ( ) const
inlineoverridevirtual

Returns true iff this process class is able to process views.

View execution of a process, also known as view context, is mainly implemented by the following member functions:

bool ProcessImplementation::CanExecuteOn( const View&, String& ) bool ProcessImplementation::ExecuteOn( View& )

which must be reimplemented by any instance class corresponding to a process with view execution capabilities.

Note
The default implementation of this function returns true, so by default a process is supposed to be executable on views. This is indeed the case for the vast majority of processes.

Implements pcl::ProcessBase.

Definition at line 561 of file MetaProcess.h.

◆ Categories()

virtual IsoString pcl::MetaProcess::Categories ( ) const
inlinevirtual

Returns the identifiers of one or more categories to which this process belongs.

Processes are organized hierarchically by categories in PixInsight. All installed processes appear classified by their categories on the Process Explorer window, and also under the Process main menu item.

This member function can return a comma-separated list of category names, or a single category name. Each category name must be a valid C identifier. If one or more of the specified names are nonempty strings that don't correspond to already existing process categories, new categories will be created and this process will be added to them. If a category already exists with the specified identifier, then this process will be added to the existing category.

If this function returns an empty string, then this process will not be associated to any particular category. It will then appear under a special, fallback pseudo-category identified as <Etc> on both the Process Explorer window and the Process main menu item.

Note
The default implementation of this function returns an empty string, so a process is not associated to any specific category unless a derived class reimplements this function.

Definition at line 205 of file MetaProcess.h.

◆ Category()

virtual IsoString pcl::MetaProcess::Category ( ) const
inlinevirtual

A synonym for Categories(), provided for compatibility with previous PCL versions.

Deprecated:
This member function has been deprecated. Use Categories() in newly produced code.

Definition at line 217 of file MetaProcess.h.

◆ Clone()

virtual ProcessImplementation* pcl::MetaProcess::Clone ( const ProcessImplementation ) const
pure virtual

Creates a new instance of this process as a duplicate of an existing process instance. Returns a pointer to the newly created process instance.

Note
This is a pure virtual member function that has to be implemented in a derived class. Every process in PixInsight must be able to generate clones of existing process instances.
See also
Create(), TestClone()

◆ Create()

virtual ProcessImplementation* pcl::MetaProcess::Create ( ) const
pure virtual

Creates a new instance of this process. Returns a pointer to the newly created process instance.

A process instance is implemented as an instance of a subclass of the ProcessImplementation class.

Note
This is a pure virtual member function that has to be implemented in a derived class. Every process in PixInsight must be able to generate new process instances.
See also
Clone()

◆ DefaultInterface()

virtual ProcessInterface* pcl::MetaProcess::DefaultInterface ( ) const
inlinevirtual

Provides a default interface for this process.

The interface addressed by this function will be activated in situations where this process is activated without a specific instance. In such situations, the core application will try to find a suitable default interface by calling this function, and if the address of a valid object is returned, the indicated interface will be launched.

An example of process activation without an instance is when the user double-clicks an item on the Process Explorer window.

When an instance is available, the core application invokes ProcessImplementation::SelectInterface() instead of this member function. An example of process activation with an instance is when the user double-clicks a process icon on the core application's workspace.

If this function returns nullptr, no interface will be launched when this process is activated without an instance.

Note
The default implementation of this function returns nullptr, so a process has no associated interface by default.
See also
ProcessImplementation::SelectInterface()

Definition at line 540 of file MetaProcess.h.

◆ Description()

String pcl::MetaProcess::Description ( ) const
inlineoverridevirtual

Returns a descriptive text for this process.

This function must provide a brief but sufficiently informative description of this process. The returned description will appear on the Process Explorer window, and should provide information about what this process does and how it can be used, avoiding too exhaustive descriptions that are better reserved for a technical manual.

Process descriptions are always printed on PixInsight consoles. This means that the text output functionality of the Console class can be used to format the string returned by this function. Refer to that class and its documentation for further information.

Note
The default implementation of this function returns an empty string, so by default a process does not provide a description. This is legal, but it is considered bad practice, so this function should be reimplemented.

Implements pcl::ProcessBase.

Definition at line 254 of file MetaProcess.h.

◆ EditPreferences()

bool pcl::MetaProcess::EditPreferences ( ) const
overridevirtual

Handles a request to edit process preferences. Returns true if the preferences were successfully edited.

Reimplement this function to allow the user to edit a set of preferences specific to this process. This task is usually implemented on a modal dialog box. In such case, if the user closes the dialog box without accepting the new preferences settings (e.g. by clicking the dialog's Cancel button) this member function should return false. This function should only return true if the user has edited and accepted a new set of preferences for this process.

Note
This function will never be called unless the CanEditPreferences() member function is reimplemented to return true.
See also
CanEditPreferences(), ProcessInterface::EditPreferences()

Implements pcl::ProcessBase.

◆ Icon()

Bitmap pcl::MetaProcess::Icon ( ) const
overridevirtual

Returns a large icon image that identifies this process.

The returned image is used to identify all instances of this process in the core application's GUI. It is used on the Process Explorer window, on all icons transporting instances of this process, and in general for every graphical item related to this process or to an instance of this process.

Implements pcl::ProcessBase.

◆ IconImageFile()

virtual String pcl::MetaProcess::IconImageFile ( ) const
inlinevirtual

Returns a large icon for this process as a path specification to an existing image file.

Supported image file formats include PNG, XPM, JPG and BMP.

For details on process icon images, see the documentation for IconImageXPM().

Note
The default implementation of this function returns an empty string.
Deprecated:
This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. All newly produced code must use IconImageSVG() or IconImageSVGFile() to define process icons in SVG format. Existing modules should also be refactored in the same way to support scalable icons.
See also
IconImageXPM()

Definition at line 424 of file MetaProcess.h.

◆ IconImageSVG()

virtual IsoString pcl::MetaProcess::IconImageSVG ( ) const
inlinevirtual

Returns the icon image of this process as a document in SVG format.

The specified image will be used to identify all instances of this process in the core application's GUI. It will be used on the Process Explorer window, on process icons of this class, and in general for every graphical item related to this process or to an instance of this process.

The returned string must be the source code of a valid SVG document representing the icon image, encoded in UTF-8.

Since core version 1.8.8-6, all process, interface and file format icons should be specified in SVG format. Raster formats, such as XPM and PNG, have been deprecated for this purpose.

If both this function and IconImageSVGFile() return an empty string, or if the specified SVG document does not exist or is not valid, a default icon will be assigned to this process automatically by the PixInsight core application.

Note
The default implementation of this function returns an empty string.
See also
IconImageSVGFile()

Definition at line 300 of file MetaProcess.h.

◆ IconImageSVGFile()

virtual String pcl::MetaProcess::IconImageSVGFile ( ) const
inlinevirtual

Returns the icon image of this process as a document in SVG format, stored as an external file.

The specified image will be used to identify all instances of this process in the core application's GUI. It will be used on the Process Explorer window, on process icons of this class, and in general for every graphical item related to this process or to an instance of this process.

The returned string must be a path to an existing file in the local file system (remote resources are not supported in current PCL versions), which must store a valid SVG document representing the icon image. The SVG source code must be encoded in UTF-8.

Since core version 1.8.8-6, all process, interface and file format icons should be specified in SVG format. Raster formats, such as XPM and PNG, have been deprecated for this purpose.

If both this function and IconImageSVG() return an empty string, or if the specified SVG document does not exist or is not valid, a default icon will be assigned to this process automatically by the PixInsight core application.

Automatic Resource Location

Process icon image files can be loaded from arbitrary locations on the local file system. However, modules typically install their process and interface icons on the /rsc/icons/module directory under the local PixInsight installation. A module can specify the "@module_icons_dir/" prefix in icon file paths to let the PixInsight core application load the corresponding SVG documents from the appropriate standard distribution directory automatically. For example, suppose that a "Bar" process, pertaining to a "Foo" module, reimplements this member function in its MetaProcess derived class as follows:

class Bar : public MetaProcess
{
public:
...
String IconImageSVGFile() const override
{
return "@module_icons_dir/Bar.svg";
}
...
};

Then the core application will attempt to load the following SVG file:

<install-dir>/rsc/icons/module/Foo/Bar.svg

where <install-dir> is the local directory where the running PixInsight core application is installed.

Note
The default implementation of this function returns an empty string.
See also
IconImageSVG()

Definition at line 367 of file MetaProcess.h.

◆ IconImageXPM()

virtual const char** pcl::MetaProcess::IconImageXPM ( ) const
inlinevirtual

Returns a large icon for this process as an image in the standard XPM format.

The specified image will be used to identify all instances of this process in the core application's GUI. It will be used on the Process Explorer window, on process icons of this class, and in general for every graphical item related to this process or to an instance of this process.

32-bit RGBA color images (including an alpha channel) are fully supported.

If this function returns nullptr, a default icon will be assigned to this process automatically.

Note
The default implementation of this function returns nullptr.
Deprecated:
This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. All newly produced code must use IconImageSVG() or IconImageSVGFile() to define process icons in SVG format. Existing modules should also be refactored in the same way to support scalable icons.
See also
IconImageFile()

Definition at line 398 of file MetaProcess.h.

◆ Id()

virtual IsoString pcl::MetaProcess::Id ( ) const
overridepure virtual

Returns an identifier for this process.

Process identifiers are unique C identifiers.

Implements pcl::ProcessBase.

◆ InitializeClass()

virtual void pcl::MetaProcess::InitializeClass ( )
inlinevirtual

Process class initialization routine.

This member function is called just after the module where this process lives has been completely installed. When this function is called, communication with the PixInsight core application is fully operative.

This function is seldom reimplemented by derived classes. Reimplement it if your process requires some initialization that cannot be accomplished in the class constructor. This includes calling PCL functions that require active communication with the PixInsight core application, as retrieving global settings for example (see the pcl/GlobalSettings.h header).

Note
The default implementation of this function does nothing.
See also
MetaProcess()

Definition at line 511 of file MetaProcess.h.

◆ IPCSetParameters()

virtual void pcl::MetaProcess::IPCSetParameters ( int  instance,
const IsoString messageUID,
const String parameters 
) const
virtual

Handles a set process parameters IPC message.

Parameters
instanceThe instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUIDUnique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.
parametersA string in UTF-16 format with process-specific parameters. Can be an empty string if no parameters were specified by the IPC message that originated this function call.
Note
This function will never be called unless the CanProcessIPCMessages() member function is reimplemented to return true.

◆ IPCStart()

virtual void pcl::MetaProcess::IPCStart ( int  instance,
const IsoString messageUID,
const String parameters 
) const
virtual

Handles a start process IPC message.

Parameters
instanceThe instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUIDUnique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.
parametersA string in UTF-16 format with process-specific parameters. Can be an empty string if no parameters were specified by the IPC message that originated this function call.
Note
This function will never be called unless the CanProcessIPCMessages() member function is reimplemented to return true.

◆ IPCStatus()

virtual int pcl::MetaProcess::IPCStatus ( int  instance,
const IsoString messageUID 
) const
virtual

Handles a get process status IPC message.

Parameters
instanceThe instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUIDUnique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.

The returned value is expected to be:

= 0 If the process is not currently in execution.

0 (process-specific positive nonzero integer codes) If the process is

now running.

< 0 (process-specific negative integer codes) If the process is not running because of an error condition.

Note
This function will never be called unless the CanProcessIPCMessages() member function is reimplemented to return true.

◆ IPCStop()

virtual void pcl::MetaProcess::IPCStop ( int  instance,
const IsoString messageUID 
) const
virtual

Handles a stop process IPC message.

Parameters
instanceThe instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUIDUnique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.
Note
This function will never be called unless the CanProcessIPCMessages() member function is reimplemented to return true.

◆ IsAssignable()

bool pcl::MetaProcess::IsAssignable ( ) const
inlineoverridevirtual

Returns true iff the instances of this process are assignable.

Assignable processes allow copying one instance to another.

If you have a good reason to avoid instance assignment for your process, then reimplement this function to return false. A good reason could be that your process has no parameters, hence no data could be assigned.

Note
The default implementation of this function returns true, so processes are assignable by default.

Implements pcl::ProcessBase.

Definition at line 754 of file MetaProcess.h.

◆ NeedsInitialization()

bool pcl::MetaProcess::NeedsInitialization ( ) const
inlineoverridevirtual

Returns true iff the instances of this process require special initialization.

Special initialization takes place just after instance creation. Sometimes, there are actions that cannot be implemented in the constructor of a process instance class. For example, this often happens when an instance must be initialized by calling reimplemented virtual functions from a base class constructor. Reimplemented virtual functions cannot be resolved from a base class constructor in C++.

If your process instance class requires some initialization that cannot be implemented in a regular constructor function, then reimplement this function to return true. In this case, you must also reimplement ProcessImplementation::Initialize() for your instance implementation class to implement the special initialization work, or a runtime exception will be thrown.

Note
The default implementation of this function returns false, so by default processes don't require special instance initialization.
Don't confuse the instance initialization that this function refers to with the InitializeClass() member function of MetaProcess.
See also
ProcessImplementation::Initialize()

Implements pcl::ProcessBase.

Definition at line 785 of file MetaProcess.h.

◆ NeedsValidation()

bool pcl::MetaProcess::NeedsValidation ( ) const
inlineoverridevirtual

Returns true iff the instances of this process require special validation.

Some processes may require validation of their instances just before they are executed. This is known as special validation. The core application will never execute an instance of a process if its validation function fails. To implement your special validation, reimplement this function to return true, as well as ProcessImplementation::Validate() for your instance implementation subclass, or a runtime exception will be thrown.

Note
The default implementation of this function returns false, so by default processes don't require special instance validation.
See also
ProcessImplementation::Validate()

Implements pcl::ProcessBase.

Definition at line 807 of file MetaProcess.h.

◆ operator=() [1/2]

MetaProcess& pcl::MetaProcess::operator= ( const MetaProcess )
delete

Copy assignment. Copy semantics are disabled for MetaProcess because this class represents unique server-side objects.

◆ operator=() [2/2]

MetaProcess& pcl::MetaProcess::operator= ( MetaProcess &&  x)
delete

Move assignment. Move semantics are disabled for MetaProcess because because of parent-child server-side object relations.

◆ operator[]()

const MetaParameter* pcl::MetaProcess::operator[] ( size_type  i) const

Provides access to the list of parameters defined for this process.

This member is intended for internal use of API module initialization routines. You should not need to call this function directly under normal conditions.

◆ PrefersGlobalExecution()

bool pcl::MetaProcess::PrefersGlobalExecution ( ) const
inlineoverridevirtual

Returns true iff the instances of this process prefer execution in the global context, instead of being executed on views.

Note that the option indicated by this function is just a hint to the PixInsight core application, not necessarily observed, depending on the context.

To prevent (or select) execution on a particular context, your process instance class must reimplement ProcessImplementation::CanExecuteOn() and/or ProcessImplementation::CanExecuteGlobal(), as appropriate.

Note
The default implementation of this function returns false, so by default processes prefer execution on views, instead of execution in the global context.

Implements pcl::ProcessBase.

Definition at line 828 of file MetaProcess.h.

◆ ProcessCommandLine()

virtual int pcl::MetaProcess::ProcessCommandLine ( const StringList argv) const
virtual

Handles a command line invocation. Returns a conventional exit code (customarily, zero signals a "normal" or successful execution).

Parameters
argvThe list of command-line arguments.
Note
This function will never be called unless the CanProcessCommandLines() member function is reimplemented to return true.
See also
CanProcessCommandLines()

◆ ScriptComment()

String pcl::MetaProcess::ScriptComment ( ) const
inlineoverridevirtual

Returns a brief description for generated scripts.

The returned text is intended to provide a brief comment to describe this process and its parameters, for quick reference on generated scripts. When writing these comments, think as you do when you're commenting your own source code.

Note
The default implementation of this function returns an empty string, so by default processes provide no script comments.

Implements pcl::ProcessBase.

Definition at line 270 of file MetaProcess.h.

◆ SmallIcon()

Bitmap pcl::MetaProcess::SmallIcon ( ) const
overridevirtual

Returns a small icon image that identifies this process.

For details on process icon images, see the documentation for Icon().

Small icons are used on interface elements where screen space must be preserved. Two good examples are the Process Explorer window and the ProcessContainer interface.

Deprecated:
This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. Small icons are deprecated because all process and interface icons must now be specified in SVG format. SVG icons can be resized automatically to the required dimensions.

Implements pcl::ProcessBase.

◆ SmallIconImageFile()

virtual String pcl::MetaProcess::SmallIconImageFile ( ) const
inlinevirtual

Returns a small icon for this process as a path specification to an existing image file.

Supported image file formats include PNG, XPM, JPG and BMP.

For details on small process icon images, see the documentation for SmallIconImageXPM().

Deprecated:
This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. All newly produced code must use IconImageSVG() or IconImageSVGFile() to define process icons in SVG format. Existing modules should also be refactored in the same way to support scalable icons.
See also
SmallIconImageXPM()

Definition at line 480 of file MetaProcess.h.

◆ SmallIconImageXPM()

virtual const char** pcl::MetaProcess::SmallIconImageXPM ( ) const
inlinevirtual

Returns a small icon for this process as an image in the standard XPM format.

For details on process icon images, see the documentation for IconImageXPM().

Small icons are used on interface elements where screen space must be preserved. Two good examples are the History Explorer window and the ProcessContainer interface.

When this function is not reimplemented in a derived class, the core PixInsight application automatically generates a small icon by resampling down the large icon provided by IconImageXPM().

You normally should not need to reimplement this function; the core application usually does a fine work resampling large icons to obtain reduced versions.

Deprecated:
This member function has been deprecated since core version 1.8.8-6. It is still available for compatibility with existing modules that depend on it, but it will be removed in a future version of PCL. All newly produced code must use IconImageSVG() or IconImageSVGFile() to define process icons in SVG format. Existing modules should also be refactored in the same way to support scalable icons.
See also
SmallIconImageFile()

Definition at line 457 of file MetaProcess.h.

◆ TestClone()

virtual ProcessImplementation* pcl::MetaProcess::TestClone ( const ProcessImplementation p) const
inlinevirtual

Creates a new instance of this process as a duplicate of an existing process instance, for strict testing purposes. Returns a pointer to the newly created process instance.

In certain situations, the core application needs a temporary process instance exclusively for testing purposes. This happens, for example, to verify if a given instance can be executed on a given view, or in the global context, during complex GUI operations. The core application tries to optimize GUI performance by calling this function when possible.

If your process can provide a substantially simplified version of an existing instance, and such a simplified version still is able to know if it can be executed globally or on a given view, then reimplement this function.

For example, if your process requires (or may require) some megabytes of data to work, but these data are not needed for testing purposes, then it is a pretty good candidate to reimplement this function. In practice, however, requiring a reimplementation of this function is infrequent.

Note
The default implementation of this function returns Clone( p ).
See also
Clone()

Definition at line 737 of file MetaProcess.h.

◆ Version()

uint32 pcl::MetaProcess::Version ( ) const
inlineoverridevirtual

Returns a version number for this process, encoded as a hexadecimal number.

For example, version 1.0.5 should be returned as 0x105, and version 3.11.5 as 0x3B5. The default return value is 0x100, corresponding to version 1.0.0.

Implements pcl::ProcessBase.

Definition at line 230 of file MetaProcess.h.


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