//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   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 &lt;Etc&gt; 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:
    *
    * &lt;install-dir&gt;/rsc/icons/module/Foo/Bar.svg
    *
    * where &lt;install-dir&gt; 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
