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

	~MetaProcess () noexcept(false) override

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 ProcessImplementation *	Clone (const ProcessImplementation &) const =0

virtual ProcessImplementation *	Create () const =0

virtual ProcessInterface *	DefaultInterface () 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

MetaProcess &	operator= (const MetaProcess &)=delete

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

const MetaParameter *	operator[] (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 ProcessImplementation *	TestClone (const ProcessImplementation &p) const

uint32	Version () const override

Public Member Functions inherited from pcl::MetaObject
	MetaObject (const MetaObject &)=delete

	MetaObject (MetaObject &&x)=delete

	MetaObject (MetaObject *parent)

virtual	~MetaObject () noexcept(false)

size_type	Length () const

MetaObject &	operator= (const MetaObject &)=delete

MetaObject &	operator= (MetaObject &&x)=delete

const MetaObject *	operator[] (size_type i) const

MetaObject *	Parent ()

const MetaObject *	Parent () const

Public Member Functions inherited from pcl::ProcessBase
	ProcessBase ()

virtual	~ProcessBase () noexcept(false)

Additional Inherited Members
Public Types inherited from pcl::MetaObject
using	children_list = IndirectArray< MetaObject >

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

pcl::MetaProcess::~MetaProcess ( )

inlineoverridenoexcept

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

Definition at line 119 of file MetaProcess.h.

◆ 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 685 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 660 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 643 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 592 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 625 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.

Set Process Parameters. Handled by a reimplementation of the IPCSetParameters() 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 933 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 567 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 546 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 260 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 430 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 306 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 373 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 404 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 517 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

instance	The instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUID	Unique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.
parameters	A 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

instance	The instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUID	Unique identifier of the IPC message that originated this call. This parameter can be used for task logging purposes.
parameters	A 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

instance	The instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUID	Unique 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

instance	The instance number of the running PixInsight core application. This is an integer > 0, which can be used for task logging purposes.
messageUID	Unique 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 760 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 791 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 813 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 834 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

argv	The 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 276 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 486 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 463 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 743 of file MetaProcess.h.

◆ Version()

uint32 pcl::MetaProcess::Version ( ) const

inlineoverridevirtual

Returns the current version number of this process.

Process version numbers are usually encoded in hexadecimal format. For example, version 1.0.5 should be returned as 0x105, and version 3.11.5 as 0x3B5. The value returned by default is 0x100, corresponding to version 1.0.0.

Process version numbers are useful to manage different implementations of processes, especially when instances are deserialized from existing projects, process icons, etc. The ProcessInstance::Version() member function can be used to retrieve the version number of the process implementation that originated a particular instance of a process.

Implements pcl::ProcessBase.

Definition at line 236 of file MetaProcess.h.

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

MetaProcess.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MetaProcess() [1/3]

◆ ~MetaProcess()

◆ MetaProcess() [2/3]

◆ MetaProcess() [3/3]

Member Function Documentation

◆ Aliases()

◆ BrowseDocumentation()

◆ CanBrowseDocumentation()

◆ CanEditPreferences()

◆ CanProcessCommandLines()

◆ CanProcessGlobal()

◆ CanProcessImages()

◆ CanProcessIPCMessages()

◆ CanProcessViews()

◆ Categories()

◆ Category()

◆ Clone()

◆ Create()

◆ DefaultInterface()

◆ Description()

◆ EditPreferences()

◆ Icon()

◆ IconImageFile()

◆ IconImageSVG()

◆ IconImageSVGFile()

◆ IconImageXPM()

◆ Id()

◆ InitializeClass()

◆ IPCSetParameters()

◆ IPCStart()

◆ IPCStatus()

◆ IPCStop()

◆ IsAssignable()

◆ NeedsInitialization()

◆ NeedsValidation()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ PrefersGlobalExecution()

◆ ProcessCommandLine()

◆ ScriptComment()

◆ SmallIcon()

◆ SmallIconImageFile()

◆ SmallIconImageXPM()

◆ TestClone()

◆ Version()