1031 lines
41 KiB
C++
1031 lines
41 KiB
C++
// ____ ______ __
|
|
// / __ \ / ____// /
|
|
// / /_/ // / / /
|
|
// / ____// /___ / /___ PixInsight Class Library
|
|
// /_/ \____//_____/ PCL 2.4.23
|
|
// ----------------------------------------------------------------------------
|
|
// pcl/MetaProcess.h - Released 2022-03-12T18:59:29Z
|
|
// ----------------------------------------------------------------------------
|
|
// This file is part of the PixInsight Class Library (PCL).
|
|
// PCL is a multiplatform C++ framework for development of PixInsight modules.
|
|
//
|
|
// Copyright (c) 2003-2022 Pleiades Astrophoto S.L. All Rights Reserved.
|
|
//
|
|
// Redistribution and use in both source and binary forms, with or without
|
|
// modification, is permitted provided that the following conditions are met:
|
|
//
|
|
// 1. All redistributions of source code must retain the above copyright
|
|
// notice, this list of conditions and the following disclaimer.
|
|
//
|
|
// 2. All redistributions in binary form must reproduce the above copyright
|
|
// notice, this list of conditions and the following disclaimer in the
|
|
// documentation and/or other materials provided with the distribution.
|
|
//
|
|
// 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
|
|
// of their contributors, may be used to endorse or promote products derived
|
|
// from this software without specific prior written permission. For written
|
|
// permission, please contact info@pixinsight.com.
|
|
//
|
|
// 4. All products derived from this software, in any form whatsoever, must
|
|
// reproduce the following acknowledgment in the end-user documentation
|
|
// and/or other materials provided with the product:
|
|
//
|
|
// "This product is based on software from the PixInsight project, developed
|
|
// by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
|
|
//
|
|
// Alternatively, if that is where third-party acknowledgments normally
|
|
// appear, this acknowledgment must be reproduced in the product itself.
|
|
//
|
|
// THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
|
|
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
|
|
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
// EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
|
|
// INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
|
|
// DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
// POSSIBILITY OF SUCH DAMAGE.
|
|
// ----------------------------------------------------------------------------
|
|
|
|
#ifndef __PCL_MetaProcess_h
|
|
#define __PCL_MetaProcess_h
|
|
|
|
/// \file pcl/MetaProcess.h
|
|
|
|
#ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION
|
|
|
|
#include <pcl/Defs.h>
|
|
#include <pcl/Diagnostics.h>
|
|
|
|
#include <pcl/MetaObject.h>
|
|
#include <pcl/ProcessBase.h>
|
|
#include <pcl/StringList.h>
|
|
|
|
namespace pcl
|
|
{
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
class View;
|
|
class ImageWindow;
|
|
class ProcessImplementation;
|
|
class ProcessInterface;
|
|
class MetaParameter;
|
|
|
|
/*!
|
|
* \class MetaProcess
|
|
* \brief A formal description of a PixInsight process.
|
|
*
|
|
* %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 <em>process
|
|
* instance implementation class</em>, 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 <em>process categories</em> in PixInsight. A
|
|
* process category groups similar or related processes together. The whole set
|
|
* of process categories forms a <em>categorized tree</em> of processes that
|
|
* can be accessed, for example, from the %Process Explorer window in the core
|
|
* PixInsight GUI.
|
|
*
|
|
* \sa MetaModule, MetaParameter, ProcessImplementation
|
|
*/
|
|
class PCL_CLASS MetaProcess : public MetaObject, public ProcessBase
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
* Constructs a %MetaProcess object.
|
|
*/
|
|
MetaProcess();
|
|
|
|
/*!
|
|
* Destroys this %MetaProcess object. Also destroys all MetaParameter
|
|
* children of this %MetaProcess.
|
|
*/
|
|
virtual ~MetaProcess() noexcept( false )
|
|
{
|
|
}
|
|
|
|
/*!
|
|
* Copy constructor. Copy semantics are disabled for %MetaProcess because
|
|
* this class represents unique server-side objects.
|
|
*/
|
|
MetaProcess( const MetaProcess& ) = delete;
|
|
|
|
/*!
|
|
* Copy assignment. Copy semantics are disabled for %MetaProcess because
|
|
* this class represents unique server-side objects.
|
|
*/
|
|
MetaProcess& operator =( const MetaProcess& ) = delete;
|
|
|
|
/*!
|
|
* Move constructor. Move semantics are disabled for %MetaProcess because
|
|
* because of parent-child server-side object relations.
|
|
*/
|
|
MetaProcess( MetaProcess&& x ) = delete;
|
|
|
|
/*!
|
|
* Move assignment. Move semantics are disabled for %MetaProcess because
|
|
* because of parent-child server-side object relations.
|
|
*/
|
|
MetaProcess& operator =( MetaProcess&& x ) = delete;
|
|
|
|
/*!
|
|
*/
|
|
virtual IsoString Id() const override = 0;
|
|
|
|
/*!
|
|
* Returns a list of alias identifiers for this process.
|
|
*
|
|
* A process can have one or more <em>alias identifiers</em>. 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).
|
|
*
|
|
* \sa Id()
|
|
*/
|
|
virtual IsoString Aliases() const
|
|
{
|
|
return IsoString();
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*/
|
|
virtual IsoString Categories() const
|
|
{
|
|
return IsoString(); // General category
|
|
}
|
|
|
|
/*!
|
|
* A synonym for Categories(), provided for compatibility with previous PCL
|
|
* versions.
|
|
*
|
|
* \deprecated This member function has been deprecated. Use Categories() in newly
|
|
* produced code.
|
|
*/
|
|
virtual IsoString Category() const // ### PCL 2.x: Remove
|
|
{
|
|
return Categories();
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*/
|
|
uint32 Version() const override
|
|
{
|
|
return 0x100;
|
|
}
|
|
|
|
/*!
|
|
* 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 \e should be
|
|
* reimplemented.
|
|
*/
|
|
String Description() const override
|
|
{
|
|
return String();
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*/
|
|
String ScriptComment() const override
|
|
{
|
|
return String();
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa IconImageSVGFile()
|
|
*/
|
|
virtual IsoString IconImageSVG() const
|
|
{
|
|
return IsoString();
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* <b>Automatic Resource Location</b>
|
|
*
|
|
* 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:
|
|
*
|
|
* \code
|
|
* class Bar : public MetaProcess
|
|
* {
|
|
* public:
|
|
* ...
|
|
*
|
|
* String IconImageSVGFile() const override
|
|
* {
|
|
* return "@module_icons_dir/Bar.svg";
|
|
* }
|
|
*
|
|
* ...
|
|
* };
|
|
* \endcode
|
|
*
|
|
* 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.
|
|
*
|
|
* \sa IconImageSVG()
|
|
*/
|
|
virtual String IconImageSVGFile() const
|
|
{
|
|
return String();
|
|
}
|
|
|
|
/*!
|
|
* Returns a <em>large icon</em> 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.
|
|
*
|
|
* \sa IconImageFile()
|
|
*/
|
|
virtual const char** IconImageXPM() const
|
|
{
|
|
return nullptr;
|
|
}
|
|
|
|
/*!
|
|
* Returns a <em>large icon</em> 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.
|
|
*
|
|
* \sa IconImageXPM()
|
|
*/
|
|
virtual String IconImageFile() const
|
|
{
|
|
return String();
|
|
}
|
|
|
|
/*!
|
|
* Returns a <em>small icon</em> 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.
|
|
*
|
|
* \sa SmallIconImageFile()
|
|
*/
|
|
virtual const char** SmallIconImageXPM() const
|
|
{
|
|
return nullptr;
|
|
}
|
|
|
|
/*!
|
|
* Returns a <em>small icon</em> 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.
|
|
*
|
|
* \sa SmallIconImageXPM()
|
|
*/
|
|
virtual String SmallIconImageFile() const
|
|
{
|
|
return String();
|
|
}
|
|
|
|
/*!
|
|
*/
|
|
Bitmap Icon() const override;
|
|
|
|
/*!
|
|
*/
|
|
Bitmap SmallIcon() const override;
|
|
|
|
/*!
|
|
* %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.
|
|
*
|
|
* \sa MetaProcess()
|
|
*/
|
|
virtual void InitializeClass()
|
|
{
|
|
}
|
|
|
|
/*!
|
|
* 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 \e instance. In
|
|
* such situations, the core application will try to find a suitable
|
|
* <em>default interface</em> 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.
|
|
*
|
|
* \sa ProcessImplementation::SelectInterface()
|
|
*/
|
|
virtual ProcessInterface* DefaultInterface() const
|
|
{
|
|
return nullptr; // by default, processes have no associated interfaces.
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this process class is able to process views.
|
|
*
|
|
* View execution of a process, also known as <em>view context</em>, 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.
|
|
*/
|
|
bool CanProcessViews() const override
|
|
{
|
|
return true;
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this process class can be executed globally.
|
|
*
|
|
* Global execution of a process, also known as <em>global context</em>, 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.
|
|
*/
|
|
bool CanProcessGlobal() const override
|
|
{
|
|
return true;
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*/
|
|
bool CanProcessImages() const override
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa ProcessCommandLine()
|
|
*/
|
|
bool CanProcessCommandLines() const override
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa EditPreferences()
|
|
*/
|
|
bool CanEditPreferences() const override
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa BrowseDocumentation()
|
|
*/
|
|
bool CanBrowseDocumentation() const override
|
|
{
|
|
return true;
|
|
}
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa Clone()
|
|
*/
|
|
virtual ProcessImplementation* Create() const = 0;
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa Create(), TestClone()
|
|
*/
|
|
virtual ProcessImplementation* Clone( const ProcessImplementation& ) const = 0;
|
|
|
|
/*!
|
|
* 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 ).
|
|
*
|
|
* \sa Clone()
|
|
*/
|
|
virtual ProcessImplementation* TestClone( const ProcessImplementation& p ) const
|
|
{
|
|
return Clone( p );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff the instances of this process are \e 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.
|
|
*/
|
|
bool IsAssignable() const override
|
|
{
|
|
return true; // by default, processes are considered assignable.
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff the instances of this process require <em>special
|
|
* initialization</em>.
|
|
*
|
|
* 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.
|
|
*
|
|
* \note Don't confuse the instance initialization that this function refers
|
|
* to with the InitializeClass() member function of %MetaProcess.
|
|
*
|
|
* \sa ProcessImplementation::Initialize()
|
|
*/
|
|
bool NeedsInitialization() const override
|
|
{
|
|
return false; // by default, process instances are not initialized.
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff the instances of this process require <em>special
|
|
* validation</em>.
|
|
*
|
|
* Some processes may require validation of their instances just before they
|
|
* are executed. This is known as <em>special validation</em>. 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.
|
|
*
|
|
* \sa ProcessImplementation::Validate()
|
|
*/
|
|
bool NeedsValidation() const override
|
|
{
|
|
return false; // by default, process instances are not validated.
|
|
}
|
|
|
|
/*!
|
|
* 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 \e 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.
|
|
*/
|
|
bool PrefersGlobalExecution() const override
|
|
{
|
|
return false; // by default, processes prefer execution on views.
|
|
}
|
|
|
|
/*!
|
|
* Handles a command line invocation. Returns a conventional exit code
|
|
* (customarily, zero signals a "normal" or successful execution).
|
|
*
|
|
* \param argv The list of command-line arguments.
|
|
*
|
|
* \note This function will never be called unless the
|
|
* CanProcessCommandLines() member function is reimplemented to return true.
|
|
*
|
|
* \sa CanProcessCommandLines()
|
|
*/
|
|
virtual int ProcessCommandLine( const StringList& argv ) const;
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa CanEditPreferences(), ProcessInterface::EditPreferences()
|
|
*/
|
|
bool EditPreferences() const override;
|
|
|
|
/*!
|
|
* 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.
|
|
*
|
|
* \sa CanBrowseDocumentation()
|
|
*/
|
|
bool BrowseDocumentation() const override;
|
|
|
|
/*!
|
|
* 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.
|
|
*/
|
|
const MetaParameter* operator[]( size_type i ) const;
|
|
|
|
/*!
|
|
* 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:
|
|
*
|
|
* \li <em>Start Process.</em> Handled by a reimplementation of the
|
|
* IPCStart() member function in a derived class.
|
|
*
|
|
* \li <em>Stop Process.</em> Handled by a reimplementation of the
|
|
* IPCStop() member function in a derived class.
|
|
*
|
|
* \li <em>Set Process Parameters.</em> Handled by a reimplementation of the
|
|
* IPCSetParameters() member function in a derived class.
|
|
*
|
|
* \li <em>Get Process Status.</em> 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().
|
|
*/
|
|
virtual bool CanProcessIPCMessages() const
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* Handles a start process IPC message.
|
|
*
|
|
* \param instance The instance number of the running PixInsight core
|
|
* application. This is an integer > 0, which can be used
|
|
* for task logging purposes.
|
|
*
|
|
* \param messageUID Unique identifier of the IPC message that originated
|
|
* this call. This parameter can be used for task logging
|
|
* purposes.
|
|
*
|
|
* \param 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.
|
|
*/
|
|
virtual void IPCStart( int instance, const IsoString& messageUID, const String& parameters ) const;
|
|
|
|
/*!
|
|
* Handles a stop process IPC message.
|
|
*
|
|
* \param instance The instance number of the running PixInsight core
|
|
* application. This is an integer > 0, which can be used
|
|
* for task logging purposes.
|
|
*
|
|
* \param 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.
|
|
*/
|
|
virtual void IPCStop( int instance, const IsoString& messageUID ) const;
|
|
|
|
/*!
|
|
* Handles a set process parameters IPC message.
|
|
*
|
|
* \param instance The instance number of the running PixInsight core
|
|
* application. This is an integer > 0, which can be used
|
|
* for task logging purposes.
|
|
*
|
|
* \param messageUID Unique identifier of the IPC message that originated
|
|
* this call. This parameter can be used for task logging
|
|
* purposes.
|
|
*
|
|
* \param 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.
|
|
*/
|
|
virtual void IPCSetParameters( int instance, const IsoString& messageUID, const String& parameters ) const;
|
|
|
|
/*!
|
|
* Handles a get process status IPC message.
|
|
*
|
|
* \param instance The instance number of the running PixInsight core
|
|
* application. This is an integer > 0, which can be used
|
|
* for task logging purposes.
|
|
*
|
|
* \param 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.
|
|
*/
|
|
virtual int IPCStatus( int instance, const IsoString& messageUID ) const;
|
|
|
|
private:
|
|
|
|
void PerformAPIDefinitions() const override;
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
} // pcl
|
|
|
|
#endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION
|
|
|
|
#endif // __PCL_MetaProcess_h
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// EOF pcl/MetaProcess.h - Released 2022-03-12T18:59:29Z
|