// ____ ______ __ // / __ \ / ____// / // / /_/ // / / / // / ____// /___ / /___ PixInsight Class Library // /_/ \____//_____/ PCL 2.4.23 // ---------------------------------------------------------------------------- // pcl/ProcessInterface.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_ProcessInterface_h #define __PCL_ProcessInterface_h /// \file pcl/ProcessInterface.h #ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION #include #include #include #include #include #endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION namespace pcl { // ---------------------------------------------------------------------------- /*! * \namespace pcl::InterfaceFeature * \brief Provides symbolic constants defining feature flags to customize * process interfaces. * * Besides defining their specific GUI components and behavior, process * interfaces can be customized in a standardized way by means of a series of * flags that control the contents and functionality of their interface * control bars. Those flags are defined through symbolic constants in the * InterfaceFeature namespace. * * An interface control bar is a managed control located at its parent * interface window's bottom side. It is a relatively small panel where a * number of standard tool buttons and a one-line text area can be customized. * * A standard process interface window has the following layout in PixInsight: * * 
 *    +---------------------------------+
 *    |      Interface Title Bar        +
 *    +---------------------------------+
 *    |                                 |
 *    |     Module-Defined              |
 *    |     Interface Client Area       |
 *    |                                 |
 *    +---------------------------------+
 *    | Info Area                       |
 *    +---------------------------------+
 *    | D A G T E X             B V P R |
 *    +---------------------------------+
 *
* * Where the two sections at the bottom form the interface's * control bar: * * \li Info Area is a one-line text label that can be used to provide * some feedback and information to the user. The contents of the info area can * be modified programmatically, but cannot be changed by the user. * * \li D = %Process Drag %Object, used to create a new process instance * by dragging it with the mouse. The new instance can be dragged for execution * on selected views, to create process icons, to add instances to a process * container, etc. * * \li A = Apply button, used for execution of a new process instance on * the current view or window. * * \li G = Apply Global button, used for execution of a new process * instance in the global context. * * \li T = Real-Time %Preview button, to attach this interface to the * real-time previewing system. * * \li E = Execute button, used to commit execution of a dynamic * interface. * * \li X = Cancel button, used to cancel execution of a dynamic * interface. * * \li B = Browse Documentation button. When this button is activated, * the default behavior is to open the Documentation Browser interface and load * it with the documentation for the process for which this open the %Process * Explorer window and show the . * * \li V = Track %View check box. When this check box is checked, the * interface should modify its behavior in some way as a function of the * current view. This check box generates calls to * ProcessInterface::TrackViewUpdated(). Interfaces using this feature * also need receiving ProcessInterface::ImageFocused() notifications. * * \li P = Preferences button, to open a modal dialog box where * process and interface-specific preferences can be edited. * * \li R = Reset button, to reset the current instance to a default * state. * * The following symbolic constants have been publicly defined for interface * feature flags: * * * * * * * * * * * * * * * * * *
InterfaceFeature::None This effectively suppresses a interface's control bar
InterfaceFeature::DragObject %Process drag object - To generate new process instances
InterfaceFeature::ApplyToViewButton Apply button - To execute a process on the active view
InterfaceFeature::ApplyGlobalButton Apply Global button - To execute a process in the global context
InterfaceFeature::RealTimeButton Real-Time Preview button - To activate the real-time preview interface
InterfaceFeature::ExecuteButton Execute button - To commit a dynamic interface
InterfaceFeature::CancelButton Cancel button - To cancel a dynamic interface
InterfaceFeature::BrowseDocumentationButton Browse documentation button - Browse process-specific documentation
InterfaceFeature::TrackViewButton Track View check box - To activate/deactivate tracking of the current view
InterfaceFeature::PreferencesButton Preferences button - To edit process and interface-specific preferences
InterfaceFeature::ResetButton Reset button - To reset process instance parameters
InterfaceFeature::InfoArea Info Area - To create a single-line text area
InterfaceFeature::Default A default set of flags for static interfaces
InterfaceFeature::DefaultGlobal A default set of flags for static interfaces that execute globally
InterfaceFeature::DefaultDynamic A default set of flags for dynamic interfaces
* * More functionality can be added to interface control bars in future * PixInsight and PCL releases. */ namespace InterfaceFeature { enum mask_type { None = 0x00000000, // This effectively suppresses a interface's control bar DragObject = 0x00000001, // Process drag object - To generate new process instances ApplyToViewButton = 0x00000002, // Apply button - To execute a process on the active view ApplyGlobalButton = 0x00000004, // Apply Global button - To execute a process in the global context RealTimeButton = 0x00000008, // Real-Time Preview button - To activate the real-time preview interface ExecuteButton = 0x00000010, // Execute button - To commit a dynamic interface CancelButton = 0x00000020, // Cancel button - To cancel a dynamic interface BrowseDocumentationButton = 0x00000080, // Browse Documentation button - To browse process-specific documentation TrackViewButton = 0x00000100, // Track View check box - To activate/deactivate tracking of the current view PreferencesButton = 0x00000400, // Preferences button - To edit process and interface-specific preferences ResetButton = 0x00000800, // Reset button - To reset process instance parameters InfoArea = 0x00010000, // Info Area - To create a single-line text area Default = DragObject | ApplyToViewButton | BrowseDocumentationButton | ResetButton, // A default set of flags for static interfaces DefaultGlobal = DragObject | ApplyGlobalButton | BrowseDocumentationButton | ResetButton, // A default set of flags for static interfaces that execute globally DefaultDynamic = DragObject | ExecuteButton | CancelButton | BrowseDocumentationButton | ResetButton // A default set of flags for dynamic interfaces }; } /*! * \class pcl::InterfaceFeatures * \brief A collection of interface feature flags. */ typedef Flags InterfaceFeatures; // ---------------------------------------------------------------------------- #ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION // ---------------------------------------------------------------------------- class PCL_CLASS MetaProcess; class PCL_CLASS ProcessImplementation; class PCL_CLASS ProcessInstance; class PCL_CLASS VectorGraphics; class PCL_CLASS View; // ---------------------------------------------------------------------------- /*! * \class ProcessInterface * \brief Client-side interface to a PixInsight process interface window. * * ### TODO: PCL 2.1.x: Rename this class to %ProcessInterfaceImplementation * ### TODO: PCL 2.2: New %ProcessInterface class for intermodule communication * * ### TODO: Write a detailed description for %ProcessInterface. */ class PCL_CLASS ProcessInterface : public Control, public MetaObject { public: /*! * Constructs a process interface window. */ ProcessInterface(); /*! * Destroys a %ProcessInterface object. */ virtual ~ProcessInterface() noexcept( false ) { } /*! * Returns a reference to a null %ProcessInterface instance. A null * %ProcessInterface does not correspond to an existing interface window in * the PixInsight core application. */ static ProcessInterface& Null(); /*! * Returns an identifier for this interface. * * Interface identifiers must be unique (within the set of installed * interfaces), valid C identifiers. * * \note Although an arbitrary identifier can be used for a process * interface, it is customary (and also a good idea, for the sake of * clarity) to assign the same identifier to both a process and its * standard interface. For example, \c FastRotation is used as the * identifier of the FastRotation process and its interface window. */ virtual IsoString Id() const = 0; /*! * Returns a list of alias identifiers for this interface. * * An interface can have one or more alias identifiers. Aliases are * useful to maintain compatibility with previous versions of an interface. * * When the PixInsight core application loads a project, it automatically * replaces alias interface identifiers with actual (current) identifiers. * This allows a developer to change the identifier of a process interface * without breaking compatibility with existing projects. * * The returned string is a comma-separated list of distinct identifiers * that will be treated as synonyms to the actual identifier of this * interface, which is returned by the Id() member function. Two installed * interfaces can't have the same alias, so each identifier included in the * list must be unique across all process interfaces 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 a pointer to the process associated with this interface. * * In general, each interface window works mainly for a particular process. * This is what is known as the standard interface of a process in * PixInsight. */ virtual MetaProcess* Process() const = 0; /*! * Returns a version number for this interface, 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. * * \deprecated This function has been deprecated and should not be used. * Interfaces no longer need version numbers. The value returned by this * member function is always ignored by the PixInsight core application. */ virtual uint32 Version() const { return 0x100; } /*! * Returns a description of this interface. * * This function must provide a brief description of the functionality and * purpose of this process interface. This should include which * process(es) can be interfaced, and how. * * \deprecated This function has been deprecated and should not be used. * Interfaces must be described by the process(es) that use them. The value * returned by this member function is always ignored by the PixInsight core * application. */ virtual String Description() const { return String(); } /*! * Returns the icon image of this process interface as a document in SVG * format. * * The specified image will be used as an icon appearing on the interface * window's title bar. To facilitate the visual identification of processes * and their interfaces, most reimplementations of this function should * normally return the same SVG document returned by its interfaced process' * reimplementation of MetaProcess::IconImageSVG(). * * 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 interface 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 interface as a document in SVG * format, stored as an external file. * * The specified image will be used as an icon appearing on the interface * window's title bar. To facilitate the visual identification of processes * and their interfaces, most reimplementations of this function should * normally return the same SVG document returned by its interfaced process' * reimplementation of MetaProcess::IconImageSVGFile(). * * 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 interface automatically by the * PixInsight core application. * * Automatic Resource Location * * See MetaProcess::IconImageSVGFile() for important information that is * equally applicable to this member function. * * \note The default implementation of this function returns an empty * string. * * \sa IconImageSVG() */ virtual String IconImageSVGFile() const { return String(); } /*! * Returns a large icon for this interface as an image in the * standard XPM format. * * The specified image will be used as an icon appearing on the interface * window's title bar. To facilitate the visual identification of processes * and their interfaces, most reimplementations of this function should * normally return the same SVG document returned by its interfaced process' * reimplementation of MetaProcess::IconImageXPM(). * * 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 * interface 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 interface 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 large icon for this interface as a path specification * to an existing image file. * * Supported image file formats include PNG, XPM, JPG and BMP. * * For details on interface 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 interface 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 small icon for this interface as an image in the * standard XPM format. * * For details on interface icon images, see the documentation for * IconImageXPM(). * * Small icons are used on interface elements where screen space must be * preserved. This may include iconized interface windows. When this * function is not reimplemented in a derived class, the PixInsight core * 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 generate * reduced versions. * * \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 interface 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 small icon for this interface as a path specification * to an existing image file. * * Supported image file formats include PNG, XPM, JPG and BMP. * * For details on small interface icon images, see the documentation for * SmallIconImageXPM(). * * \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 interface 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(); } /*! * Returns a combination of flags defining the contents and functionality of * the interface control bar in this process interface. * * The returned value must be an OR'ed combination of flags defined by * symbolic constants in the InterfaceFeature namespace. * * \note The default implementation of this function returns * InterfaceFeature::Default, which is a default set of flags appropriate * for most interfaces working for processes that execute on views. * * \sa InterfaceFeature */ virtual InterfaceFeatures Features() const { return InterfaceFeature::Default; } /*! * Function called when the user clicks the Apply button on the interface * control bar. * * For this function to be invoked, the InterfaceFeature::ApplyToViewButton * flag must be included in the set of feature flags returned by the * Features() member function, or a reimplementation of it, as appropriate. * * \note The default implementation of this function obtains a new process * instance by calling NewProcess() for this interface, then executes it on * the active view, if there is one. */ virtual void ApplyInstance() const; /*! * Function called when the user clicks the Apply Global button on the * interface control bar. * * For this function to be invoked, the InterfaceFeature::ApplyGlobalButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * \note The default implementation of this function obtains a new process * instance by calling NewProcess() for this interface, then executes it in * the global context. */ virtual void ApplyInstanceGlobal() const; /*! * Function called when the user clicks the Execute button on the interface * control bar. * * For this function to be invoked, the InterfaceFeature::ExecuteButton flag * must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * \note The default implementation of this function does nothing. It is * reimplemented by derived classes implementing dynamic interfaces, to * commit the active dynamic session. An example is the standard DynamicCrop * interface. The reimplementation of this function in the DynamicCrop * interface executes the defined crop/rotate/rescale operation on the * interface's dynamic target image and terminates the dynamic session. */ virtual void Execute() { } /*! * Function called when the user clicks the Cancel button on the * interface control bar. * * For this function to be invoked, the InterfaceFeature::CancelButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * \note The default implementation of this function terminates the active * dynamic session, if there is one. It is unlikely that this function needs * a reimplementation in a derived class, unless a nonstandard interface * behavior is desired. */ virtual void Cancel(); /*! * Function called when the user toggles the pushed state of the Real Time * Preview control bar button. * * \param active True if the Real Time Preview button is currently * active (or pushed down); false if the button is * unpushed. * * For this function to be invoked, the InterfaceFeature::RealTimeButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * Derived classes for interfaces that use the real time previewing system * must reimplement this function to control ownership of the Real Time * Preview window and provide real-time preview images, as necessary. * * \note The default implementation of this function does nothing. */ virtual void RealTimePreviewUpdated( bool active ) { } /*! * Function called when the user clicks the Browse Documentation button on * the interface control bar. Returns true if the documentation was loaded * successfully. * * For this function to be invoked, the * InterfaceFeature::BrowseDocumentationButton flag must be included in the * set of feature flags returned by a reimplementation of the Features() * member function in a derived class. * * The default implementation of this member function is a wrapper for the * MetaProcess::BrowseDocumentation() virtual member function of the process * class associated with this interface. In other words, it basically does * the following: * * \code * const MetaProcess* P = Process(); * if ( P != nullptr ) * if ( P->CanBrowseDocumentation() ) * P->BrowseDocumentation(); * \endcode * * In general, a derived class should not need to reimplement this member * function, as the default behavior is appropriate in most cases. */ virtual bool BrowseDocumentation() const; /*! * Function called when the user toggles the pushed state of the Track %View * control bar button. * * \param active True if the Track %View button is currently active * (pushed down); false if the button is unpushed. * * For this function to be invoked, the InterfaceFeature::TrackViewButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * %View tracking is used by interfaces that modify their behavior * and/or information contents as a function of the current view in the * PixInsight application's GUI. When a view is selected, the interface * receives an ImageFocused() notification and, if view tracking is active, * it takes the opportune actions. * * \note The default implementation of this function does nothing. * * \sa Control::IsTrackViewActive(), Control::SetTrackViewActive(), * ImageFocused() */ virtual void TrackViewUpdated( bool active ) { } /*! * Function called when the user clicks the Preferences control bar button. * * For this function to be invoked, the InterfaceFeature::PreferencesButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * If you reimplement this function, its standard behavior is launching a * modal dialog to allow editing preferences and options pertaining to the * process(es) associated to this interface. * * \note Note that along with this function, a process should reimplement * the MetaProcess::EditPreferences() member in its MetaProcess subclass, * and that both implementations should be coherent. The default * implementation of this function does nothing. * * \sa MetaProcess::CanEditPreferences(), MetaProcess::EditPreferences() */ virtual void EditPreferences() { } /*! * Function called when the user clicks the Reset control bar button. * * For this function to be invoked, the InterfaceFeature::ResetButton * flag must be included in the set of feature flags returned by a * reimplementation of the Features() member function in a derived class. * * If you reimplement this function, its standard behavior is performing a * reset of the current process instance in this interface, loading its * default parameter values, and updating interface elements in consequence. * * \note The default implementation of this function does nothing. */ virtual void ResetInstance() { } /*! * Interface initialization routine. * * This member function is called when the control handle of this interface * becomes valid, that is, just after the window holding this interface has * been created. * * You can reimplement this function to create all child controls of this * interface, as well as to set up a number of important control features, * like a window title, colors, fonts, and so on. * * \deprecated This function has been deprecated and should not be used. * Interface initialization should be carried out using the \e deferred * \e initialization technique by reimplementing the Launch() virtual member * function. See the documentation for these functions for more detailed * information. * * \note The default implementation of this function does nothing. * * \sa Launch( const MetaProcess&, const ProcessImplementation*, bool&, unsigned& ), * Launch( unsigned ) */ virtual void Initialize() { } /*! * %Process interface launch routine. * * \param process Reference to the metaprocess describing the process * class that is launching this interface, either directly * as its default interface, or through an existing * process instance. * * \param instance Address of a process instance that is trying to launch * this interface, or zero if it is being launched * directly as the default interface of the \a process. * * \param[out] dynamic True if this interface wants to be launched in * dynamic mode; false if this interface will launch as a * static interface. * * \param flags Reserved for future extensions - must not be modified. * * This function is called whenever an interface is about to be \e launched. * An interface can be launched either directly as the default interface of * a process class (e.g., from PixInsight's %Process Explorer window), or * through an existing process instance (e.g., by double-clicking a process * icon). The argument values identify the process class and, if nonzero, * the process instance. * * This function must return true if it accepts to be launched under the * conditions specified by the arguments. After successfully launching an * interface from a process instance (i.e., if \a instance is nonzero), the * ValidateProcess() member function is invoked with a reference to the * instance. If the instance is validated, the ImportProcess() function is * finally called. * * If this function returns true, the \a dynamic referenced argument * variable must be set to \c true if this interface wants to start in * dynamic mode. If an interface launches in dynamic mode, a final call to * EnterDynamicMode() will occur before the interface window is shown and/or * activated. Note that the actual dynamic session will not really * start until a first view is selected by the user to serve as a * dynamic target. * * Interface Initialization * * Initializing an interface means building its sub-controls and setting up * a number of important control features, such as a window title, colors, * fonts, adjusting sizes, and so on. This job can be done by reimplementing * the Initialize() member function, which the PixInsight core application * calls as soon as the control handle of this interface becomes valid, that * is, just after the window holding this interface has been created. * * However, the Initialize() function is now deprecated and the standard way * to initialize an interface is by reimplementing its %Launch() function to * perform the initialization work the first time the interface is * launched. This technique is known as deferred initialization * of a process interface, and has the important advantage that it minimizes * resources and memory usage because an interface is only initialized if it * is ever used. Most interfaces are almost never launched by the user, * except on special occasions, so investing resources for them continually * is inefficient in general. All standard PixInsight interfaces use the * deferred initialization technique for that reason. * * However, developers using the deferred initialization technique must be * very careful to ensure that their interfaces will never try to access any * child controls and other interface elements prior to initializing them. * This is particularly important if an interface responds to platform * notifications or events generated by other controls. * * \note The default implementation of this function sets \a dynamic = false * and returns true, so all process interfaces are static by default. * * \sa Initialize(), LaunchCount(), Launch( unsigned ) */ virtual bool Launch( const MetaProcess& process, const ProcessImplementation* instance, bool& dynamic, unsigned& flags ) { dynamic = false; // interfaces are static by default return true; } /*! * Launches this interface with its default process. * * \param flags Reserved for future extensions - must be zero. * * Returns true if the interface could be launched successfully; false in * the event of error. * * This is a convenience function to launch an interface without a process * instance. It is functionally equivalent to the following code: * * \code * bool Launch( ProcessInterface& iface, unsigned flags = 0 ) * { * const MetaProcess* process = iface.Process(); * if ( process == nullptr ) * return false; * bool notUsed; * return iface.Launch( *process, nullptr, notUsed, flags ); * } * \endcode * * \sa Launch( const MetaProcess&, const ProcessImplementation*, bool&, unsigned& ), */ bool Launch( unsigned flags = 0 ); /*! * Returns the number of times this interface has been launched since the * beginning of the current PixInsight session. * * \sa Launch() */ size_type LaunchCount() const { return m_launchCount; } /*! * %Process instantiation function. * * Interfaces capable of generating process instances must reimplement this * function to create a new process instance, whose address is returned. * * The newly created instance should reflect the current state of this * interface. Interfaces usually maintain a private process instance, whose * parameters are modifiable through the interface's controls. Then a * reimplementation of this function simply creates a duplicate of the * private instance and returns its address. * * Returning \e arbitrary instances that have no logical connection with * the \e visible state of this interface is considered bad practice, and is * a main reason to deny certification of a PixInsight module. This is * because the user has always the right to know exactly what she or he can * expect to get, based on the information shown by an interface on its * controls. * * \note If an interface does not reimplement this function, then it will be * a plain tool with no processing capabilities. This is because the default * implementation of this function returns nullptr, meaning that no process * instance can be generated. In this case, it is \e mandatory that the * interface reimplements the IsInstanceGenerator() member function to * return false. * * \sa IsInstanceGenerator(), NewTestProcess(), MetaProcess::Clone() */ virtual ProcessImplementation* NewProcess() const { return nullptr; } /*! * Test instantiation function. * * This function is invoked when a new instance is necessary for strict * testing purposes exclusively, not to perform actual processing. * * In certain situations, the core application needs a \e 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. * * For example, the PixInsight core application tries to create temporary * test instances each time the user drags a process icon over an image, to * learn if the instance that the icon encapsulates can be executed on the * view that holds the image. If the user drops the icon, then a regular, * non-test instance is generated by calling NewProcess(), then it is * executed, if possible. If the checks carried out by the dragged test * instances take significant time, PixInsight's user interface can suffer * from a severe performace degradation. * * 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. * * 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 quite infrequent. * * \note The default implementation of this function just returns * NewProcess(). * * \sa DistinguishesTestInstances(), NewProcess(), MetaProcess::TestClone() */ virtual ProcessImplementation* NewTestProcess() const { return NewProcess(); } /*! * Returns true iff this interface can generate new process instances. * * If your interface has no actual processing capabilities, then reimplement * this function to return false. This helps the PixInsight core application * to save resources and improve GUI performance. * * An interface has no processing capabilities if its NewProcess() member * function returns zero. This happens if NewProcess() is not reimplemented. * Although quite infrequent, an interface can be an instance generator * \e sometimes, as a function of process parameters or other circumstances. * In this case both NewProcess() and IsInstanceGenerator() must be * reimplemented to provide coherent values. * * \note The default implementation of this function returns true, so all * interfaces are instance generators by default. * * \sa NewProcess() */ virtual bool IsInstanceGenerator() const { return true; } /*! * Returns true iff this interface can provide simplified versions of process * instances for strict testing purposes. * * For example, the PixInsight core application tries to create \e temporary * test instances each time the user drags a process icon over an image, to * learn if the instance that the icon encapsulates can be executed on the * view that holds the image. If the user drops the icon, then a regular, * non-test instance is generated and executed, if possible. If the checks * carried out by the dragged test instances take significant time, * PixInsight's user interface can suffer from a performace degradation. * * If you can provide substantially simplified instances, but still able to * know if they can be used in the context of a particular view, then * reimplement this function to return true, and also NewTestProcess() to * return simplified test instances. * * \note The default implementation of this function returns false, so * interfaces don't distinguish between normal (executable) and test * instances by default. * * \sa NewTestProcess() */ virtual bool DistinguishesTestInstances() const { return false; } /*! * Instance validation function. * * \param instance Reference to a process instance that is being validated * before being imported by this interface. * * \param[out] whyNot If this function returns false, it should return also * a brief text (256 characters maximum) in this string, * explaining why the specified \a instance is not a valid * instance to be imported by this interface. * * This function will not be called unless the RequiresInstanceValidation() * member function is reimplemented to return true in a derived class. * * Instance validation takes place when an instance is about to be imported * by this interface. Importing a process instance means that its parameters * and data will be acquired by this interface, to edit them through the * available controls and GUI resources. * * \note The default implementation of this function returns false. This is * because it should be reimplemented if RequiresInstanceValidation() has * already been reimplemented to return true. * * \sa RequiresInstanceValidation(), ImportProcess() */ virtual bool ValidateProcess( const ProcessImplementation& instance, String& whyNot ) const { whyNot.Clear(); return false; // Force a reimplementation if RequiresInstanceValidation() = true } /*! * Returns true iff this interface requires validation of a process instance * before acquisition via ImportProcess(). * * If you actually need this kind of validation, reimplement this function * to return true, and also the ValidateProcess() function to perform the * instance validation. * * \note The default implementation of this function returns false, so * instances are not validated before acquiring them with ImportProcess(). * * \sa ValidateProcess(), ImportProcess() */ virtual bool RequiresInstanceValidation() const { return false; } /*! * Instance import function. * * This function is called when a process instance is being acquired by this * interface. For example, this happens when the user drags a process icon * to the control bar panel of this interface, or when an instance has been * launched and it has selected this interface from a reimplementation of * ProcessImplementation::SelectInterface(). * * When an instance is imported by an interface, instance parameters and * data items are usually acquired by the interface to edit them through its * available controls and GUI resources. * * This function returns true iff the specified instance is accepted and * successfully imported. * * This function is never called if CanImportInstances() has been * reimplemented to return false. * * Note that ValidateProcess() has been called just before this function, * with a reference to the same instance, only if a reimplementation of * RequiresInstanceValidation() returns true. In this case, this function is * not called if ValidateProcess() does not return true. * * You must reimplement this function if your interface has processing * capabilities. Only plain tools don't need to reimplement this function, * since they know nothing about process instances. * * \note The default implementation of this function returns false, so by * default an interface cannot import instances. * * \sa ValidateProcess(), CanImportInstances(), * ProcessImplementation::SelectInterface() */ virtual bool ImportProcess( const ProcessImplementation& ) { return false; } /*! * Returns true iff this interface is able to import process instances. * * If your interface has no processing capabilities, you should * reimplement this function to return false. * * \note The default implementation of this function returns true. * * \sa ImportProcess() */ virtual bool CanImportInstances() const { return true; } /*! * Function called when the real-time preview image needs an update, and * this interface is the owner of the Real-Time Preview system. * * \param[in,out] image Reference to a shared image where the real-time * rendition would be generated. This image contains pixel * data of a view selected for real-time previewing. A * subsequent call to GenerateRealTimePreview() would * receive a reference to an image with the same pixel * data, for effective real-time preview generation. * * \param view Reference to a view that is currently selected in the * Real-Time Preview system of the core application. The * passed \a image contains a representation of the image * in this view. * * \param rect Current real-time region in \a view image coordinates. * If a nonempty rectangle is received through this * parameter, then the input \a image contains a * representation of the corresponding rectangular region * of the \a view's image. If this parameter is an empty * rectangle, it must be ignored and \a image is a * representation of the entire \a view's image. * * \param zoomLevel Indicates the integer zoom ratio that has been applied * to the specified \a image, with respect to the original * view's image. If this parameter is a negative number, * it represents a reduction factor; for example, -2 * corresponds to a 1:2 reduction ratio, meaning that each * pixel of \a image corresponds to 4 source pixels in the * view being previewed. If this parameter is a positive * number, it can only be equal to 1, indicating that each * pixel in \a image corresponds to one source pixel. In * other words, real-time preview images can be scaled * down, but are never magnified or scaled up. * * Returns true if the real-time preview requires an update for the * specified image; false if no update is required. * * If this function returns true, a subsequent call to * GenerateRealTimePreview() will occur when appropriate. * * The passed \a image, \a view and \a rect objects cannot be * modified in any way by this function. * * \note The default implementation of this function returns false. * * \sa GenerateRealTimePreview(), CancelRealTimePreview(), RealTimePreview */ virtual bool RequiresRealTimePreviewUpdate( const UInt16Image& image, const View& view, const Rect& rect, int zoomLevel ) const { return false; } /*! * Function called to generate a new real-time preview rendition. * * \param[in,out] image Reference to a shared image where the real-time * rendition must be generated. On input, this image * contains pixel data of a view selected for real-time * previewing. On output, this image must be transformed * to represent a preview of the current process instance * being edited on this process interface. * * \param view Reference to a view that is currently selected in the * Real-Time Preview system of the core application. The * passed \a image contains a representation of the image * in this view. * * \param rect Current real-time region in \a view image coordinates. * If a nonempty rectangle is received through this * parameter, then the input \a image contains a * representation of the corresponding rectangular region * of the \a view's image. If this parameter is an empty * rectangle, it must be ignored and \a image is a * representation of the entire \a view's image. * * \param zoomLevel Indicates the integer zoom ratio that has been applied * to the specified \a image, with respect to the original * view's image. If this parameter is a negative number, * it represents a reduction factor; for example, -2 * corresponds to a 1:2 reduction ratio, meaning that each * pixel of \a image corresponds to 4 source pixels in the * view being previewed. If this parameter is a positive * number, it can only be equal to 1, indicating that each * pixel in \a image corresponds to one source pixel. In * other words, real-time preview images can be scaled * down, but are never magnified or scaled up. * * \param[out] info Reference to a string where a brief informative text * (256 characters maximum) can optionally be stored to * describe some special circumstances about the generated * rendition. Typically, this string can be used to inform * about an inexact or partial rendition, for example * because the applied reduction ratio (\a zoomLevel) * does not allow a reasonably accurate representation of * some process features. * * Returns true to signal that the passed \a image has been modified and can * now be used to update the current real-time preview. Returns false to * indicate that the \a image has not been altered by this function, and * hence that the current real-time preview update should be aborted. * * The passed \a view and \a rect objects cannot be modified in any * way by this function. A reimplementation of this function cannot be * used to modify a view indirectly - we mean it! * * \note The default implementation of this function returns false without * modifying the passed \a image. * * \sa RequiresRealTimePreviewUpdate(), CancelRealTimePreview(), * RealTimePreview */ virtual bool GenerateRealTimePreview( UInt16Image& image, const View& view, const Rect& rect, int zoomLevel, String& info ) const { return false; } /*! * Function called to request cancellation of the ongoing real-time preview * generation process. * * The core application may call this member function when the current * real-time generation process (which is being carried out by a * reimplemented GenerateRealTimePreview() function) should be aborted * immediately and unconditionally. * * The core application can make such a request at its own discretion---and * your interface should be ready to honor it during a real-time generation * task---, but currently (as of PixInsight core version 1.8.0) this only * happens if the real-time progress dialog has been made visible and the * user has closed it prematurely (e.g., by clicking its Cancel button). * * \note The default implementation of this function simulates a manual * deactivation of the Real-Time Preview button of this interface by calling * Control::DeactivateRealTimePreview(). If your real-time generation code * is coherent with the current state of your interface, you normally should * not need to reimplement this member function. * * \sa RequiresRealTimePreviewUpdate(), GenerateRealTimePreview(), * RealTimePreview::ShowProgressDialog(), RealTimePreview */ virtual void CancelRealTimePreview() { DeactivateRealTimePreview(); } /*! * Returns true iff this interface can be a dynamic interface. * * A dynamic interface is a process interface working in dynamic * mode. In dynamic mode, an interface provides a high degree of * interaction with the user through a set of special functions that allow * direct, real-time communication with the core application's GUI. This * includes the possibility of generating arbitrary graphical contents on * image views, and receiving pointing device (mouse, tablet) messages. * * Note that an interface can work in both static and dynamic modes (not * simultaneously, of course), depending on the value returned by the * Launch() function. However, dynamic interface semantics will not be * available to an interface unless it reimplements this function to return * true. This has been done in this way to help saving platform resources, * which is a design principle of PCL. * * If this function returns false (as it does by default), dynamic process * semantics will not be available for this interface. * * \note The default implementation of this function returns false, so * dynamic interface semantics are disabled by default. * * \sa Launch() */ virtual bool IsDynamicInterface() const { return false; } /*! * Function called when a new dynamic mode session is about to * start. Returns true if the new dynamic session can continue; false if it * should be interrupted. * * \note The default implementation of this function returns true. * * \sa ExitDynamicMode() */ virtual bool EnterDynamicMode() { return true; } /*! * Function called just after a dynamic session has been terminated. * * \note The default implementation of this function does nothing. * * \sa EnterDynamicMode() */ virtual void ExitDynamicMode() { } /*! * Function called when the mouse cursor enters the viewport of a \a view, * during an active dynamic session. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseLeave(), DynamicMouseMove(), DynamicMousePress(), * DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel() */ virtual void DynamicMouseEnter( View& view ) { } /*! * Function called when the mouse cursor leaves the viewport of a \a view, * during an active dynamic session. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseEnter(), DynamicMouseMove(), DynamicMousePress(), * DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel() */ virtual void DynamicMouseLeave( View& view ) { } /*! * Function called when the mouse cursor is displaced on a view, during an * active dynamic session. * * \param view Reference to a view over which the mouse cursor has * been displaced. * * \param cursorPos New mouse cursor position in image coordinates. * * \param buttons Indicates the current states of all mouse buttons. This * value is an OR'ed combination of MouseButton flags. A * flag set indicates a pressed mouse button. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseEnter(), DynamicMouseLeave(), DynamicMousePress(), * DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel() */ virtual void DynamicMouseMove( View& view, const DPoint& cursorPos, unsigned buttons, unsigned modifiers ) { } /*! * Function called when a mouse button is pressed on a view, during an * active dynamic session. * * \param view Reference to a view over which a mouse button has been * pressed. * * \param cursorPos Current mouse cursor position in image coordinates. * * \param button Identifies the mouse button that has been pressed. This * value is a unique MouseButton flag. * * \param buttons Indicates the current states of all mouse buttons. This * value is an OR'ed combination of MouseButton flags. A * flag set indicates a pressed mouse button. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), * DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel() */ virtual void DynamicMousePress( View& view, const DPoint& cursorPos, int button, unsigned buttons, unsigned modifiers ) { } /*! * Function called when a mouse button is released on a view, during an * active dynamic session. * * \param view Reference to a view over which a mouse button has been * released. * * \param cursorPos Current mouse cursor position in image coordinates. * * \param button Identifies the mouse button that has been released. * This value is a unique MouseButton flag. * * \param buttons Indicates the current states of all mouse buttons. This * value is an OR'ed combination of MouseButton flags. A * flag set indicates a pressed mouse button. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), * DynamicMousePress(), DynamicMouseDoubleClick(), DynamicMouseWheel() */ virtual void DynamicMouseRelease( View& view, const DPoint& cursorPos, int button, unsigned buttons, unsigned modifiers ) { } /*! * Function called when the primary mouse button is double-clicked on a * view, during an active dynamic session. * * \param view Reference to a view over which the primary mouse button * has been double-clicked. * * \param cursorPos Current mouse cursor position in image coordinates. * * \param buttons Indicates the current states of all mouse buttons. This * value is an OR'ed combination of MouseButton flags. A * flag set indicates a pressed mouse button. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * \note The default implementation of this function does nothing. * * \sa DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), * DynamicMousePress(), DynamicMouseRelease(), DynamicMouseWheel() */ virtual void DynamicMouseDoubleClick( View& view, const DPoint& cursorPos, unsigned buttons, unsigned modifiers ) { } /*! * Function called if a key is pressed when a view has the keyboard focus, * during an active dynamic session. * * \param view Reference to the view that had the keyboard focus when * a key was pressed. * * \param key A KeyCode code identifying the keyboard key that has * been pressed. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * This function returns true if it processes the keyboard press event. If * false is returned, then the keyboard event may propagate to other * elements in the PixInsight core application GUI. * * \note The default implementation of this function returns false. * * \sa DynamicKeyRelease() */ virtual bool DynamicKeyPress( View& view, int key, unsigned modifiers ) { return false; } /*! * Function called if a key is released when a view has the keyboard focus, * during an active dynamic session. * * \param view Reference to the view that had the keyboard focus when * a key was released. * * \param key A KeyCode code identifying the keyboard key that has * been released. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * This function returns true if it processes the keyboard release event. If * false is returned, then the keyboard event may propagate to other * elements in the PixInsight core application GUI. * * \note The default implementation of this function returns false. * * \sa DynamicKeyPress() */ virtual bool DynamicKeyRelease( View& view, int key, unsigned modifiers ) { return false; } /*! * Function called when the mouse wheel is rotated while the mouse cursor is * over a view, during an active dynamic session. * * \param view Reference to a view over which the mouse cursor was * located when the mouse wheel was rotated. * * \param cursorPos Current mouse cursor position in image coordinates. * * \param wheelDelta Wheel rotation increment. A positive increment * indicates that the wheel has been rotated in the * forward direction; negative increments correspond to * backwards rotation. For example, negative increments * should be used to scroll down a scrollable area, as a * document browser. * * \param buttons Indicates the current states of all mouse buttons. This * value is an OR'ed combination of MouseButton flags. A * flag set indicates a pressed mouse button. * * \param modifiers Indicates the current states of all keyboard modifiers. * This value is an OR'ed combination of KeyModifier * flags. A flag set indicates a pressed modifier key. * * This function returns true if it processes the wheel rotation event. If * false is returned, then the wheel event will propagate to other elements * in the PixInsight core application GUI. * * \note The default implementation of this function returns false. * * \sa DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), * DynamicMousePress(), DynamicMouseRelease(), DynamicMouseDoubleClick() */ virtual bool DynamicMouseWheel( View& view, const DPoint& cursorPos, int wheelDelta, unsigned buttons, unsigned modifiers ) { return false; } /*! * Function called when a view's screen rendition needs to be updated, * during an active dynamic session. * * \param view Reference to a view that requires a screen update. * * \param rect Update region in image coordinates. * * This function \e must be reimplemented by dynamic interfaces that * maintain their own graphical content over image views. * * This function must return false if this interface requires no screen * update for the specified update region. * * If this function returns true, then a subsequent call to DynamicPaint() * will occur as soon as possible, including this update region, probably * into a wider region, due to optimization of screen updates. * * \note The default implementation of this function returns false. * * \sa DynamicPaint() */ virtual bool RequiresDynamicUpdate( const View& view, const DRect& rect ) const { return false; } /*! * Function called when a view's screen rendition has been updated. * * \param view Reference to a view where the specified update region * should be redrawn by this interface. * * \param graphics Reference to a vector graphics context, where all * screen drawing work must be performed. * * \param rect Update region in image coordinates. * * This function \e must be reimplemented by dynamic interfaces that * maintain their own graphical content over image views. * * When this function is invoked, the update region will contain just the * screen rendition of the target \a view's image, with display functions * and color management transformations applied as appropriate, but without * any additional vectorial contents such as preview rectangles, selections, * auxiliary geometric items, cursors, etc, which are always rendered * \e after this function returns. * * When this function is called, the update region has already been set as * the current clipping region of the \a graphics context in viewport * coordinates. The module being invoked can only define a clipping region * as an intersection with the update rectangle, but not outside it. In * other words, this function can only paint \e inside the specified update * rectangle. Any attempt to define a larger clipping region, for example by * calling Graphics::SetClipRect(), is illegal and will be blocked by the * PixInsight core application. * * \note The default implementation of this function does nothing. * * \sa RequiresDynamicUpdate(), VectorGraphics */ virtual void DynamicPaint( const View& view, VectorGraphics& graphics, const DRect& rect ) const { } /*! * \defgroup image_notifications Image Notification Functions * * The PixInsight core application calls image notification functions to * keep interfaces informed about changes and events involving views and * their images. * * For a process interface to receive image notifications, the corresponding * ProcessInterface subclass must reimplement * ProcessInterface::WantsImageNotifications() to return true. */ /*! * Returns true iff this interface will receive image notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive image notifications by default. * * \sa \ref image_notifications "Image Notification Functions" */ virtual bool WantsImageNotifications() const { return false; } /*! * Notification sent when a new view has been created. * * \param view Reference to the view that has been created. Can be * either a main view or a preview. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageCreated( const View& view ) { } /*! * Notification sent when the image in a view has been modified. * * \param view Reference to the view whose image has been modified. * Can be either a main view or a preview. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageUpdated( const View& view ) { } /*! * Notification sent when the identifier of a view has been changed. * * \param view Reference to the view whose identifier has been * changed. Can be either a main view or a preview. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageRenamed( const View& view ) { } /*! * Notification sent when an existing view is about to be destroyed. * * \param view Reference to the view that will be destroyed. Can be * either a main view or a preview. * * When an image window is closed and it has one or more previews defined, * an ImageDeleted() notification is sent for each of its previews, then a * final notification is sent for its main view. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageDeleted( const View& view ) { } /*! * Notification sent when a view has been activated and has received the * input focus. * * \param view Reference to the view that has been activated and * focused. This is from now on the current active * view in the core application's GUI. \a view can be * either a main view or a preview. * * If the \a view is a preview, this notification implicitly means that its * parent image window has been activated and is now the topmost, active * window in the current workspace. In this case, however, a notification * for the window's main view is not sent; only the active view is notified. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageFocused( const View& view ) { } /*! * Notification sent when a view has been locked for read and/or write * operations. * * \param view Reference to the view that has been locked. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageLocked( const View& view ) { } /*! * Notification sent when a view has been unlocked for read and/or write * operations. * * \param view Reference to the view that has been unlocked. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageUnlocked( const View& view ) { } /*! * Notification sent when the screen transfer functions (STF) have * been enabled for a view. * * \param view Reference to a view whose STF have been enabled. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageSTFEnabled( const View& view ) { } /*! * Notification sent when the screen transfer functions (STF) have * been disabled for a view. * * \param view Reference to a view whose STF have been disabled. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageSTFDisabled( const View& view ) { } /*! * Notification sent when the screen transfer functions (STF) of a * view have been updated. * * \param view Reference to a view whose STF have been updated. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageSTFUpdated( const View& view ) { } /*! * Notification sent when the parameters of the RGB working space * (RGBWS) of a view have been updated. * * \param view Reference to a view whose RGBWS has been updated. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageRGBWSUpdated( const View& view ) { } /*! * Notification sent when color management (CM) has been enabled * for a view. * * \param view Reference to a view for which color management has been * enabled. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageCMEnabled( const View& view ) { } /*! * Notification sent when color management (CM) has been disabled * for a view. * * \param view Reference to a view for which color management has been * disabled. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageCMDisabled( const View& view ) { } /*! * Notification sent when the color management (CM) parameters of a * view have been updated. * * \param view Reference to a view whose color management data or * working parameters have been modified. * * This notification is sent when a view's ICC profile is changed or * deleted, and when some color management features are modified, as * soft-proofing or gamut check, among others. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageCMUpdated( const View& view ) { } /*! * Notification sent when an image has been saved to a disk file. * * \param view Reference to a view whose image has been successfully * written to a file. * * \ingroup image_notifications * \sa \ref image_notifications "Image Notification Functions" */ virtual void ImageSaved( const View& view ) { } /*! * \defgroup mask_notifications Mask Notification Functions * * The PixInsight core application calls mask notification functions to * keep interfaces informed about changes and events involving masks of * image windows. * * For a process interface to receive mask notifications, the corresponding * ProcessInterface subclass must reimplement * ProcessInterface::WantsMaskNotifications() to return true. */ /*! * Returns true iff this interface will receive mask notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive mask notifications by default. * * \sa \ref mask_notifications "Mask Notification Functions" */ virtual bool WantsMaskNotifications() const { return false; } /*! * Notification sent when a mask has been selected for (or removed from) an * image window. * * \param view Reference to the main view of an image window for which * either a new mask has been selected, or an existing * mask has been removed. * * \ingroup mask_notifications * \sa \ref mask_notifications "Mask Notification Functions" */ virtual void MaskUpdated( const View& view ) { } /*! * Notification sent when masking has been enabled for an image window. * * \param view Reference to the main view of an image window for which * masking has been enabled. * * \ingroup mask_notifications * \sa \ref mask_notifications "Mask Notification Functions" */ virtual void MaskEnabled( const View& view ) { } /*! * Notification sent when masking has been disabled for an image window. * * \param view Reference to the main view of an image window for which * masking has been disabled. * * \ingroup mask_notifications * \sa \ref mask_notifications "Mask Notification Functions" */ virtual void MaskDisabled( const View& view ) { } /*! * Notification sent when mask visibility has been enabled for an image * window. * * \param view Reference to the main view of an image window whose * mask is now visible. * * \ingroup mask_notifications * \sa \ref mask_notifications "Mask Notification Functions" */ virtual void MaskShown( const View& view ) { } /*! * Notification sent when mask visibility has been disabled for an image * window. * * \param view Reference to the main view of an image window whose * mask is now hidden. * * \ingroup mask_notifications * \sa \ref mask_notifications "Mask Notification Functions" */ virtual void MaskHidden( const View& view ) { } /*! * \defgroup transparency_notifications Image Transparency \ * Notification Functions * * The PixInsight core application calls transparency notification functions * to keep interfaces informed about changes in transparency rendering modes * of image windows. * * For a process interface to receive transparency notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsTransparencyNotifications() to return true. */ /*! * Returns true iff this interface will receive transparency notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive transparency notifications by default. * * \sa \ref transparency_notifications * "Image Transparency Notification Functions" */ virtual bool WantsTransparencyNotifications() const { return false; } /*! * Notification sent when transparency rendering has been disabled for an * image window. * * \param view Reference to the main view of an image window for which * transparency rendering has been disabled. * * \ingroup transparency_notifications * \sa \ref transparency_notifications * "Image Transparency Notification Functions" */ virtual void TransparencyHidden( const View& view ) { } /*! * Notification sent when the current transparency rendering mode has been * updated for an image window. * * \param view Reference to the main view of an image window whose * transparency rendering mode has been updated. * * \ingroup transparency_notifications * \sa \ref transparency_notifications * "Image Transparency Notification Functions" */ virtual void TransparencyModeUpdated( const View& view ) { } /*! * \defgroup view_property_notifications View Property Notification \ * Functions * * The PixInsight core application calls view property notification * functions to keep interfaces informed about changes and events involving * view properties. * * For a process interface to receive view property notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsViewPropertyNotifications() to return true. */ /*! * Returns true iff this interface will receive view property notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive view property notifications by default. * * \sa \ref view_property_notifications "View Property Notification Functions" */ virtual bool WantsViewPropertyNotifications() const { return false; } /*! * Notification sent when a view property has been created or modified. * * \param view Reference to a view where a new property has been * created, or an existing property has been modified. * * \param property Identifier of the view property that has been created * or modified. * * \ingroup view_property_notifications * \sa \ref view_property_notifications "View Property Notification Functions" */ virtual void ViewPropertyUpdated( const View& view, const IsoString& property ) { } /*! * Notification sent when a view property has been deleted. * * \param view Reference to a view where a property has been deleted. * * \param property Identifier of the view property that has been deleted. * * \ingroup view_property_notifications * \sa \ref view_property_notifications "View Property Notification Functions" */ virtual void ViewPropertyDeleted( const View& view, const IsoString& property ) { } /*! * \defgroup readout_notifications Readout Notification Functions * * The PixInsight core application calls readout notification functions to * send real-time readout pixel values to interfaces. * * Readout operations take place when the user clicks and drags the mouse * over a view in readout mode (ImageMode::Readout). During a * readout procedure, RGBA values are read from a view's image (according to * global readout options) and sent to interfaces via readout notifications. * * For example, an interface can receive readout notifications to let the * user select a color by clicking directly over an image. The NewImage * standard interface does exactly this to select an initial color for newly * created images. * * For a process interface to receive readout notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsReadoutNotifications() to return true. */ /*! * Returns true iff this interface will receive readout notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive readout notifications by default. * * \sa \ref readout_notifications "Readout Notification Functions" */ virtual bool WantsReadoutNotifications() const { return false; } /*! * Notification sent to signal the beginning of a new readout procedure. * * \param view Reference to a view from which new readout data * notifications will be sent from now on. * * \ingroup readout_notifications * \sa \ref readout_notifications "Readout Notification Functions" */ virtual void BeginReadout( const View& view ) { } /*! * Notification sent when new readout data are available. * * \param view Reference to a view from which new readout data is * being sent. * * \param position Readout position in image coordinates. * * \param R,G,B,A New readout red, green, blue and alpha values, * respectively, in the normalized real range [0,1]. * * \note Although images can have an unlimited number of alpha channels in * PixInsight, only readout values from the first alpha channel (which * defines transparency) are sent to interfaces. * * \ingroup readout_notifications * \sa \ref readout_notifications "Readout Notification Functions" */ virtual void UpdateReadout( const View& view, const DPoint& position, double R, double G, double B, double A ) { } /*! * Notification sent to signal the end of an active readout procedure. * * \param view Reference to the view from which new readout data * notifications will no longer be sent. * * \ingroup readout_notifications * \sa \ref readout_notifications "Readout Notification Functions" */ virtual void EndReadout( const View& view ) { } /*! * \defgroup process_notifications Process Instance Notification Functions * * The PixInsight core application calls process instance notification * functions to keep interfaces informed about changes and events involving * process instances. * * For a process interface to receive process instance notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsProcessNotifications() to return true. */ /*! * Returns true iff this interface will receive process instance * notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive instance notifications by default. * * \sa \ref process_notifications "Process Instance Notification Functions" */ virtual bool WantsProcessNotifications() const { return false; } /*! * Notification sent when a new process instance has been created. * * \param instance Reference to a process instance that has been newly * created. * * \ingroup process_notifications * \sa \ref process_notifications "Process Instance Notification Functions" */ virtual void ProcessCreated( const ProcessInstance& instance ) { } /*! * Notification sent when an existing process instance has been updated. * * \param instance Reference to a process instance that has been modified. * * \ingroup process_notifications * \sa \ref process_notifications "Process Instance Notification Functions" */ virtual void ProcessUpdated( const ProcessInstance& instance ) { } /*! * Notification sent when a process instance is about to be destroyed. * * \param instance Reference to a process instance that will be destroyed. * * \ingroup process_notifications * \sa \ref process_notifications "Process Instance Notification Functions" */ virtual void ProcessDeleted( const ProcessInstance& instance ) { } /*! * Notification sent when a process instance has been saved to a disk file. * * \param instance Reference to a process instance that has been written * successfully to a disk file (for example, as part of a * .xpsm file). * * \ingroup process_notifications * \sa \ref process_notifications "Process Instance Notification Functions" */ virtual void ProcessSaved( const ProcessInstance& instance ) { } /*! * \defgroup rtpreview_notifications Real Time Preview Notification \ * Functions * * The PixInsight core application calls real time preview notification * functions to keep interfaces informed about changes and events involving * the PixInsight real time previewing system. * * For a process interface to receive real time preview notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsRealTimePreviewNotifications() to return true. */ /*! * Returns true iff this interface will receive notifications from the * real-time previewing system. * * \note The default implementation of this function returns false, so * interfaces don't receive real-time previewing notifications by default. * * \sa \ref rtpreview_notifications "Real Time Preview Notification Functions" */ virtual bool WantsRealTimePreviewNotifications() const { return false; } /*! * Notification sent when the owner of the real time previewing system has * been changed. * * \param iface Reference to a process interface that is now the owner * of the real-time previewing system. * * \ingroup rtpreview_notifications * \sa \ref rtpreview_notifications "Real Time Preview Notification Functions" */ virtual void RealTimePreviewOwnerChanged( ProcessInterface& iface ) { } /*! * Notification sent when a real time preview LUT structure has been * generated. * * \param colorModel Identifies the LUT structure that has been recalculated * and is now available. * * \ingroup rtpreview_notifications * \sa \ref rtpreview_notifications "Real Time Preview Notification Functions" * * \deprecated This function has been deprecated and should not be used. The * real-time previewing system no longer depends on look up table (LUT) * structures. */ virtual void RealTimePreviewLUTUpdated( int colorModel ) { } /*! * Notification sent when a new real-time rendition has started being * generated. * * \ingroup rtpreview_notifications * \sa \ref rtpreview_notifications "Real Time Preview Notification Functions" */ virtual void RealTimePreviewGenerationStarted() { } /*! * Notification sent when a new real-time rendition has finished being * generated. * * \ingroup rtpreview_notifications * \sa \ref rtpreview_notifications "Real Time Preview Notification Functions" */ virtual void RealTimePreviewGenerationFinished() { } /*! * \defgroup global_notifications Global Notification Functions * * The PixInsight core application calls global notification functions to * keep interfaces informed about changes and events occurring in the global * core application context. * * For a process interface to receive global notifications, the * corresponding ProcessInterface subclass must reimplement * ProcessInterface::WantsGlobalNotifications() to return true. */ /*! * Returns true iff this interface will receive global notifications. * * \note The default implementation of this function returns false, so * interfaces don't receive global notifications by default. * * \sa \ref global_notifications "Global Notification Functions" */ virtual bool WantsGlobalNotifications() const { return false; } /*! * Notification sent when the parameters of the global RGB working space * (RGBWS) have been modified. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void GlobalRGBWSUpdated() { } /*! * Notification sent when color management (CM) has been globally enabled. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void GlobalCMEnabled() { } /*! * Notification sent when color management (CM) has been globally disabled. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void GlobalCMDisabled() { } /*! * Notification sent when global color management (CM) data or working * parameters have been modified. This includes selecting a new default ICC * profile, or changing some global color management parameters, such as * default profile mismatching policies or rendering intents. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void GlobalCMUpdated() { } /*! * Notification sent when global readout options have been modified. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void ReadoutOptionsUpdated() { } /*! * Notification sent when one or more global preferences settings have been * modified. * * \ingroup global_notifications * \sa \ref global_notifications "Global Notification Functions" */ virtual void GlobalPreferencesUpdated() { } /*! * Returns a settings key that should be used for storage of all settings * data associated to this interface. * * The returned settings key string will be equal to "Interfaces/<id>/", * where <id> is the identifier of this interface, as returned by the * Id() member function. * * \note Interfaces must only use the keys returned by this function for * storage of all their settings data. Using different keys is allowed, but * it is considered bad practice in most cases. * * \sa Settings, SaveSettings(), LoadSettings() */ IsoString SettingsKey() const { return IsoString( "Interfaces/" ) + Id() + '/'; } /*! * Saves settings data for this process interface. * * This function is called automatically for all process interfaces upon * module unload. If your interface needs storing and retrieving * configuration data to remember them across sessions, then you should * reimplement this function. * * See the documentation for the LoadSettings() member function for detailed * information about saving and loading settings data for process * interfaces. * * \note This function is only invoked for interfaces that have been * launched at least once. This is because if an interface has not been used * during a session, there is no plausible reason to modify its associated * configuration data. This policy has been adopted to maximize user control * over interface preferences and configuration settings. * * \sa Settings, LoadSettings(), SettingsKey() */ virtual void SaveSettings() const { } /*! * Retrieves stored settings data for this process interface. * * This function is called automatically for all process interfaces the * first time they are launched. If your interface needs storing and * retrieving configuration data to remember them across sessions, then you * should reimplement this function. * * When saving and loading settings data, your code must use the key * returned by SettingsKey() as a prefix for the subkeys corresponding to * each settings data item. For example, the following code snippet: * * \code * IsoString key = SettingsKey() + "Geometry/"; * // ... * Settings::Write( key + "Width", Width() ); * \endcode * * would save the current width of this interface to the * "Interfaces/<id>/Geometry/Width" subkey in the global settings * space assigned to the current module. This is the recommended behavior. * * \sa Settings, SaveSettings(), SettingsKey() */ virtual void LoadSettings() { } /*! * Saves the current position and dimensions of this interface in global * settings variables. * * Call this function to save the geometry of an interface window across * sessions. The RestoreGeometry() member function can be invoked to restore * previously saved position and size data. * * Before calling this function, all interface child controls and interface * elements should have been completely initialized. If this interface is * not resizable (e.g. because the SetFixedSize() function has been called), * size data are not stored. * * This function stores geometry data in the following settings keys: * * Interfaces/<id>/Geometry/Left \n * Interfaces/<id>/Geometry/Top \n * Interfaces/<id>/Geometry/Width \n * Interfaces/<id>/Geometry/Height * * where <id> is the identifier of this interface, as returned by the * Id() member function. * * \note Normally, you should not need to call this function, unless you * have explicitly disabled the auto save geometry feature by * calling the DisableAutoSaveGeometry() member function. * * \sa RestoreGeometry(), SetDefaultPosition(), IsAutoSaveGeometryEnabled() */ void SaveGeometry() const; /*! * Restores previously saved position and dimensions of this interface from * global settings variables. Returns true if stored geometry data could be * successfully retrieved and established for this interface. * * Call this function to restore the geometry of an interface window as it * was previously saved by SaveGeometry(). This allows an interface to * \e remember its size and position on the core application's work space * across sessions. * * \note Normally, you should not need to call this function, unless you * have explicitly disabled the auto save geometry feature by * calling the DisableAutoSaveGeometry() member function. * * \sa SaveGeometry() */ bool RestoreGeometry(); /*! * Moves this interface window to a default position on the PixInsight core * application's work space. * * The default position is calculated to place the interface window centered * on the primary monitor. * * \sa SaveGeometry(), RestoreGeometry() */ void SetDefaultPosition(); /*! * Returns true iff the auto save geometry feature is currently * active for this interface. * * When auto save geometry is active, the interface \e remembers * its size and position on the PixInsight core application's worspace * across sessions. Geometry data are saved to and retrieved from global * settings variables automatically. Geometry is only saved for interfaces * that have been launched at least once. * * \note By default, the auto save geometry feature is active for * every process interface. To avoid this automatic behavior, it must be * explicitly disabled. * * \sa EnableAutoSaveGeometry(), DisableAutoSaveGeometry(), * SaveGeometry(), RestoreGeometry(), SetDefaultPosition() */ bool IsAutoSaveGeometryEnabled() const { return m_autoSaveGeometry; } /*! * Enables (or disables) the auto save geometry feature. For more * information on this feature, see the documentation for the * IsAutoSaveGeometryEnabled() member function. * * \sa DisableAutoSaveGeometry(), IsAutoSaveGeometryEnabled() */ void EnableAutoSaveGeometry( bool enable = true ) { m_autoSaveGeometry = enable; } /*! * Disables (or enables) the auto save geometry feature. For more * information on this feature, see the documentation for the * IsAutoSaveGeometryEnabled() member function. * * \sa EnableAutoSaveGeometry(), IsAutoSaveGeometryEnabled() */ void DisableAutoSaveGeometry( bool disable = true ) { EnableAutoSaveGeometry( !disable ); } /*! * Issues an %ImageUpdated notification for a view. * * \param view Reference to the view for which an ImageUpdated * notification will be sent. * * The PixInsight core application will send ImageUpdated() notifications to * all objects that listen image notifications on the entire PixInsight * platform. This includes not only other process interfaces (including the * emitter), but also a large number of interface objects and processing * resources whose states can be automatically updated in response to the * notification received. * * Broadcasting is typically used by dynamic interfaces that modify images * as a function of direct user interaction. A good example of this is the * CloneStamp interface, which broadcasts ImageUpdated notifications to * keep the whole platform consistent with image changes due to clone stamp * actions performed by the user. * * \note This member function must \e not be used on a regular basis without * having a \e really good reason to do so. An abusive use of this function, * such as too frequent calls performed during intensive real-time * operations, may degrade the performance of the whole platform due to * excessive overhead. */ static void BroadcastImageUpdated( const View& view ); /*! * Processes pending user interface events. * * Call this function to let the PixInsight core application process pending * user interface events, which may accumulate while your code is running. * * Modules typically call this function during real-time preview generation * procedures. Calling this function ensures that the GUI remains responsive * during long, calculation-intensive operations. * * If the \a excludeUserInputEvents parameter is set to true, no user input * events will be processed by calling this function. This includes mainly * mouse and keyboard events. Unprocessed input events will remain pending * and will be processed as appropriate when execution returns to * PixInsight's main event handling loop, or when this function is called * again with \a excludeUserInputEvents set to false. * * \note Do not call this function too frequently, as doing so may degrade * the performance of the whole PixInsight graphical interface. For example, * calling this function at 250 ms intervals is reasonable and more than * sufficient in most cases. Normally, you should only need to call this * function during real-time image and graphics generation procedures, or * from time-consuming processes. */ static void ProcessEvents( bool excludeUserInputEvents = false ); protected: /*! * \internal */ ProcessInterface( int ); private: size_type m_launchCount = 0; bool m_autoSaveGeometry = true; void PerformAPIDefinitions() const override; friend class InterfaceDispatcher; }; // ---------------------------------------------------------------------------- #endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION } // pcl #endif // __PCL_ProcessInterface_h // ---------------------------------------------------------------------------- // EOF pcl/ProcessInterface.h - Released 2022-03-12T18:59:29Z