High-level interface to an installed process. More...
#include <Process.h>
Inheritance diagram for pcl::Process:
Public Types | |
| using | parameter_list = Array< ProcessParameter > |
Public Member Functions | |
| Process (const IsoString &classId) | |
| Process (const Process &proc) | |
| ~Process () override | |
| IsoStringList | 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 |
| bool | CanProcessViews () const override |
| IsoStringList | Categories () const |
| String | Description () const override |
| bool | EditPreferences () const override |
| bool | HasParameter (const IsoString ¶mId) const |
| bool | HasTableColumn (const IsoString &tableId, const IsoString &colId) const |
| Bitmap | Icon () const override |
| IsoString | Id () const override |
| bool | IsAssignable () const override |
| bool | Launch () const |
| bool | NeedsInitialization () const override |
| bool | NeedsValidation () const override |
| parameter_list | Parameters () const |
| bool | PrefersGlobalExecution () const override |
| int | RunCommandLine (const String &arguments) const |
| String | ScriptComment () const override |
| Bitmap | SmallIcon () const override |
| uint32 | Version () const override |
| Public Member Functions inherited from pcl::ProcessBase | |
| ProcessBase () | |
| virtual | ~ProcessBase () noexcept(false) |
Static Public Member Functions | |
| static IsoStringList | AllProcessCategories () |
| static Array< Process > | AllProcesses () |
| static Array< Process > | ProcessesByCategory (const IsoString &category) |
Detailed Description
Process instances are high-level, managed objects that represent installed processes in the PixInsight platform. A module creates an instance of Process to gain access to an installed process through intermodule communication.
Process and MetaProcess
Process provides a description of the functionality and properties of an already installed process. Contrarily, by subclassing the MetaProcess class a module can define and implement a new process that can be installed in the PixInsight platform. MetaProcess is a formal description of a process, while Process describes an existing (and installed) process.
As a MetaProcess subclass describes how a process can be instantiated, Process allows a module to create new instances of a process that can be edited and executed. Process does not provide any process execution functionality; executable processes are represented by the ProcessInstance class.
- See also
- ProcessBase, MetaProcess, ProcessInstance
Member Typedef Documentation
◆ parameter_list
A list of process parameters.
This type is returned by the Parameters() member function to describe and identify the set of parameters of a process.
Constructor & Destructor Documentation
◆ Process() [1/2]
| pcl::Process::Process | ( | const IsoString & | classId | ) |
Constructs a Process object.
- Parameters
-
classId Identifier of an installed process in the PixInsight core application.
If successful, this constructor creates a managed alias to an installed process in the PixInsight core application.
If there is no installed process with the specified identifier, if classId is not a valid identifier, or if the alias object cannot be generated for some reason, this constructor throws an Error exception with the corresponding error message. Your code should guarantee that these exceptions are always caught and handled appropriately.
◆ Process() [2/2]
| pcl::Process::Process | ( | const Process & | proc | ) |
Copy constructor. Constructs an alias Process object that refers to the same process as the specified object proc.
◆ ~Process()
|
override |
Destroys a Process object.
- Note
- This destructor does not destroy or uninstall the actual process it refers to, which is part of the PixInsight core application. Only the managed alias object living in the caller module is destroyed.
Member Function Documentation
◆ Aliases()
| IsoStringList pcl::Process::Aliases | ( | ) | const |
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 object is a list of distinct identifiers that are 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.
◆ AllProcessCategories()
|
static |
Returns a list of all the currently defined process categories in the PixInsight core application.
◆ AllProcesses()
Returns a list of all the currently installed processes on the PixInsight core application.
◆ BrowseDocumentation()
|
overridevirtual |
Handles a request to browse documentation specific for this process. Returns true iff the documentation was loaded successfully.
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.
Implements pcl::ProcessBase.
◆ CanBrowseDocumentation()
|
overridevirtual |
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, so normally this member function returns true for all processes.
Implements pcl::ProcessBase.
◆ CanEditPreferences()
|
overridevirtual |
Returns true iff this process is able to edit specific preferences.
Implements pcl::ProcessBase.
◆ CanProcessCommandLines()
|
overridevirtual |
Returns true iff this process is able to process specific command-line invocations.
Implements pcl::ProcessBase.
◆ CanProcessGlobal()
|
overridevirtual |
Returns true iff this process can be executed globally.
Implements pcl::ProcessBase.
◆ CanProcessImages()
|
overridevirtual |
Returns true iff this process is able to process standalone images.
Implements pcl::ProcessBase.
◆ CanProcessViews()
|
overridevirtual |
Returns true iff this process is able to process views.
Implements pcl::ProcessBase.
◆ Categories()
| IsoStringList pcl::Process::Categories | ( | ) | const |
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 function returns a list of category names. Each category name must be a valid C identifier. If the returned list is empty, then this process is not associated with any particular category. In such case this process appears under a special, fallback pseudo-category identified as <Etc> on both the Process Explorer window and the Process main menu item.
◆ Description()
|
overridevirtual |
Returns a descriptive text for this process.
This function should provide a brief but sufficiently informative description of this process. The returned description appears 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.
Implements pcl::ProcessBase.
◆ EditPreferences()
|
overridevirtual |
Handles a request to edit process preferences. Returns true if the preferences were successfully edited.
By calling this member function for a process able to edit preferences (that is, when CanEditPreferences() returns true), the user is allowed to define a set of preferences specific to this process. Usually this task is 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 member function should only return true if the user has edited and accepted a new set of preferences for this process.
Implements pcl::ProcessBase.
◆ HasParameter()
| bool pcl::Process::HasParameter | ( | const IsoString & | paramId | ) | const |
Returns true iff this process has a parameter with the specified identifier paramId.
◆ HasTableColumn()
Returns true iff this process has a table parameter tableId with the specified column parameter colId.
◆ Icon()
|
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.
◆ Id()
|
overridevirtual |
Returns an identifier for this process.
Process identifiers are unique C identifiers.
Implements pcl::ProcessBase.
◆ IsAssignable()
|
overridevirtual |
Returns true iff the instances of this process are assignable.
Assignable processes allow copying the parameters of one instance (and possibly more module-dependent data) to another.
Implements pcl::ProcessBase.
◆ Launch()
| bool pcl::Process::Launch | ( | ) | const |
Launches this process.
If this process has an associated default interface, then its top level window is shown and activated in its current state.
If this process has no default interface, then the core application attempts to generate a default instance of the process and execute it. If the process prefers global execution (see the PrefersGlobalExecution() member function), then the default instance is executed in the global context; otherwise it is executed on the current view, if there is at least one image available.
Returns true if the process was successfully launched; false in the event of error, or if the core application was unable to launch or execute it.
◆ NeedsInitialization()
|
overridevirtual |
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++.
Implements pcl::ProcessBase.
◆ NeedsValidation()
|
overridevirtual |
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.
Implements pcl::ProcessBase.
◆ Parameters()
| parameter_list pcl::Process::Parameters | ( | ) | const |
Returns the list of parameters of this process. The list can be empty for processes that don't have parameters.
◆ PrefersGlobalExecution()
|
overridevirtual |
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. This means that the fact that this member function returns true for a process does not mean that the process cannot be executed on views.
Implements pcl::ProcessBase.
◆ ProcessesByCategory()
Returns a list of all the currently installed processes pertaining to the specified category. Pass an empty string to obtain a list of all uncategorized processes (i.e. the <Etc> fallback category).
Returns an empty list if no currently installed process pertains to the specified category.
◆ RunCommandLine()
| int pcl::Process::RunCommandLine | ( | const String & | arguments | ) | const |
Invokes the command line execution routine for this process.
- Parameters
-
arguments A string with the list of arguments that will be passed to the command line execution routine. Multiple arguments must be separated with white space characters.
If this process supports command line execution, then the corresponding command line execution routine is invoked with the specified arguments. Otherwise, this member function calls Launch(), and the specified command line arguments are ignored.
On the PixInsight platform, command line option arguments are customarily specified with leading dash characters, following the common UNIX style. Argument values are separated with equal signs. However, command line syntax and the meaning of each argument are specific to each process.
This function returns the exit code of the command line execution routine of the process. By convention, exit code zero means successful execution, and nonzero exit codes are returned to signal errors.
◆ ScriptComment()
|
overridevirtual |
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.
Implements pcl::ProcessBase.
◆ SmallIcon()
|
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.
◆ Version()
|
overridevirtual |
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.
Implements pcl::ProcessBase.
The documentation for this class was generated from the following file:
