ProcessInterface.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/ProcessInterface.h - Released 2024-06-18T15:48:54Z
// ----------------------------------------------------------------------------
// This file is part of the PixInsight Class Library (PCL).
// PCL is a multiplatform C++ framework for development of PixInsight modules.
//
// Copyright (c) 2003-2024 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
 
 
#ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION
 
#include <pcl/Defs.h>
 
#include <pcl/Control.h>
#include <pcl/ImageVariant.h>
#include <pcl/Flags.h>
#include <pcl/MetaObject.h>
 
#endif   // __PCL_BUILDING_PIXINSIGHT_APPLICATION
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
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
   };
}
 
using InterfaceFeatures = Flags<InterfaceFeature::mask_type>;
 
// ----------------------------------------------------------------------------
 
namespace RealTimePreviewGenerationFlag
{
   enum mask_type
   {
      None        = 0x00000000,  // No real-time preview generation flags
      DisableMask = 0x00000010,  // Do not render a masked real-time preview
      Invalid     = 0xFFFFFFFF
   };
}
 
using RealTimePreviewGenerationFlags = Flags<RealTimePreviewGenerationFlag::mask_type>;
 
// ----------------------------------------------------------------------------
 
#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 PCL_CLASS ProcessInterface : public Control, public MetaObject
{
public:
 
   ProcessInterface();
 
   ~ProcessInterface() noexcept( false ) override
   {
   }
 
   static ProcessInterface& Null();
 
   virtual IsoString Id() const = 0;
 
   virtual IsoString Aliases() const
   {
      return IsoString();
   }
 
   virtual MetaProcess* Process() const = 0;
 
   virtual uint32 Version() const
   {
      return 0x100;
   }
 
   virtual String Description() const
   {
      return String();
   }
 
   virtual IsoString IconImageSVG() const
   {
      return IsoString();
   }
 
   virtual String IconImageSVGFile() const
   {
      return String();
   }
 
   virtual const char** IconImageXPM() const
   {
      return nullptr;
   }
 
   virtual String IconImageFile() const
   {
      return String();
   }
 
   virtual const char** SmallIconImageXPM() const
   {
      return nullptr;
   }
 
   virtual String SmallIconImageFile() const
   {
      return String();
   }
 
   virtual InterfaceFeatures Features() const
   {
      return InterfaceFeature::Default;
   }
 
   virtual void ApplyInstance() const;
 
   virtual void ApplyInstanceGlobal() const;
 
   virtual void Execute()
   {
   }
 
   virtual void Cancel();
 
   virtual void RealTimePreviewUpdated( bool active )
   {
   }
 
   virtual bool BrowseDocumentation() const;
 
   virtual void TrackViewUpdated( bool active )
   {
   }
 
   virtual void EditPreferences()
   {
   }
 
   virtual void ResetInstance()
   {
   }
 
   virtual void Initialize()
   {
   }
 
   virtual bool Launch( const MetaProcess& process,
                        const ProcessImplementation* instance, bool& dynamic, unsigned& flags )
   {
      dynamic = false;  // interfaces are static by default
      return true;
   }
 
   bool Launch( unsigned flags = 0 );
 
   size_type LaunchCount() const
   {
      return m_launchCount;
   }
 
   virtual ProcessImplementation* NewProcess() const
   {
      return nullptr;
   }
 
   virtual ProcessImplementation* NewTestProcess() const
   {
      return NewProcess();
   }
 
   virtual bool IsInstanceGenerator() const
   {
      return true;
   }
 
   virtual bool DistinguishesTestInstances() const
   {
      return false;
   }
 
   virtual bool ValidateProcess( const ProcessImplementation& instance, String& whyNot ) const
   {
      whyNot.Clear();
      return false;  // Force a reimplementation if RequiresInstanceValidation() = true
   }
 
   virtual bool RequiresInstanceValidation() const
   {
      return false;
   }
 
   virtual bool ImportProcess( const ProcessImplementation& )
   {
      return false;
   }
 
   virtual bool CanImportInstances() const
   {
      return true;
   }
 
   virtual bool RequiresRealTimePreviewUpdate( const UInt16Image& image, const View& view,
                                               const Rect& rect, int zoomLevel ) const
   {
      return false;
   }
 
   virtual pcl::RealTimePreviewGenerationFlags RealTimePreviewGenerationFlags( UInt16Image& image, const View& view,
                                                                               const Rect& rect, int zoomLevel ) const
   {
      return RealTimePreviewGenerationFlag::None;
   }
 
   virtual bool GenerateRealTimePreview( UInt16Image& image, const View& view,
                                         const Rect& rect, int zoomLevel, String& info ) const
   {
      return false;
   }
 
   virtual void CancelRealTimePreview()
   {
      DeactivateRealTimePreview();
   }
 
   virtual bool IsDynamicInterface() const
   {
      return false;
   }
 
   virtual bool EnterDynamicMode()
   {
      return true;
   }
 
   virtual void ExitDynamicMode()
   {
   }
 
   virtual void DynamicMouseEnter( View& view )
   {
   }
 
   virtual void DynamicMouseLeave( View& view )
   {
   }
 
   virtual void DynamicMouseMove( View& view, const DPoint& cursorPos,
                                  unsigned buttons, unsigned modifiers )
   {
   }
 
   virtual void DynamicMousePress( View& view, const DPoint& cursorPos,
                                   int button, unsigned buttons, unsigned modifiers )
   {
   }
 
   virtual void DynamicMouseRelease( View& view, const DPoint& cursorPos,
                                     int button, unsigned buttons, unsigned modifiers )
   {
   }
 
   virtual void DynamicMouseDoubleClick( View& view, const DPoint& cursorPos,
                                         unsigned buttons, unsigned modifiers )
   {
   }
 
   virtual bool DynamicKeyPress( View& view, int key, unsigned modifiers )
   {
      return false;
   }
 
   virtual bool DynamicKeyRelease( View& view, int key, unsigned modifiers )
   {
      return false;
   }
 
   virtual bool DynamicMouseWheel( View& view, const DPoint& cursorPos,
                                   int wheelDelta, unsigned buttons, unsigned modifiers )
   {
      return false;
   }
 
   virtual bool RequiresDynamicUpdate( const View& view, const DRect& rect ) const
   {
      return false;
   }
 
   virtual void DynamicPaint( const View& view, VectorGraphics& graphics, const DRect& rect ) const
   {
   }
 
   virtual bool WantsImageNotifications() const
   {
      return false;
   }
 
   virtual void ImageCreated( const View& view )
   {
   }
 
   virtual void ImageUpdated( const View& view )
   {
   }
 
   virtual void ImageRenamed( const View& view )
   {
   }
 
   virtual void ImageDeleted( const View& view )
   {
   }
 
   virtual void ImageFocused( const View& view )
   {
   }
 
   virtual void ImageLocked( const View& view )
   {
   }
 
   virtual void ImageUnlocked( const View& view )
   {
   }
 
   virtual void ImageSTFEnabled( const View& view )
   {
   }
 
   virtual void ImageSTFDisabled( const View& view )
   {
   }
 
   virtual void ImageSTFUpdated( const View& view )
   {
   }
 
   virtual void ImageRGBWSUpdated( const View& view )
   {
   }
 
   virtual void ImageCMEnabled( const View& view )
   {
   }
 
   virtual void ImageCMDisabled( const View& view )
   {
   }
 
   virtual void ImageCMUpdated( const View& view )
   {
   }
 
   virtual void ImageSaved( const View& view )
   {
   }
 
   virtual bool WantsMaskNotifications() const
   {
      return false;
   }
 
   virtual void MaskUpdated( const View& view )
   {
   }
 
   virtual void MaskEnabled( const View& view )
   {
   }
 
   virtual void MaskDisabled( const View& view )
   {
   }
 
   virtual void MaskShown( const View& view )
   {
   }
 
   virtual void MaskHidden( const View& view )
   {
   }
 
   virtual bool WantsTransparencyNotifications() const
   {
      return false;
   }
 
   virtual void TransparencyHidden( const View& view )
   {
   }
 
   virtual void TransparencyModeUpdated( const View& view )
   {
   }
 
   virtual bool WantsViewPropertyNotifications() const
   {
      return false;
   }
 
   virtual void ViewPropertyUpdated( const View& view, const IsoString& property )
   {
   }
 
   virtual void ViewPropertyDeleted( const View& view, const IsoString& property )
   {
   }
 
   virtual bool WantsReadoutNotifications() const
   {
      return false;
   }
 
   virtual void BeginReadout( const View& view )
   {
   }
 
   virtual void UpdateReadout( const View& view, const DPoint& position, double R, double G, double B, double A )
   {
   }
 
   virtual void EndReadout( const View& view )
   {
   }
 
   virtual bool WantsProcessNotifications() const
   {
      return false;
   }
 
   virtual void ProcessCreated( const ProcessInstance& instance )
   {
   }
 
   virtual void ProcessUpdated( const ProcessInstance& instance )
   {
   }
 
   virtual void ProcessDeleted( const ProcessInstance& instance )
   {
   }
 
   virtual void ProcessSaved( const ProcessInstance& instance )
   {
   }
 
   virtual bool WantsRealTimePreviewNotifications() const
   {
      return false;
   }
 
   virtual void RealTimePreviewOwnerChanged( ProcessInterface& iface )
   {
   }
 
   virtual void RealTimePreviewLUTUpdated( int colorModel )
   {
   }
 
   virtual void RealTimePreviewGenerationStarted()
   {
   }
 
   virtual void RealTimePreviewGenerationFinished()
   {
   }
 
   virtual bool WantsGlobalNotifications() const
   {
      return false;
   }
 
   virtual void GlobalRGBWSUpdated()
   {
   }
 
   virtual void GlobalCMEnabled()
   {
   }
 
   virtual void GlobalCMDisabled()
   {
   }
 
   virtual void GlobalCMUpdated()
   {
   }
 
   virtual void ReadoutOptionsUpdated()
   {
   }
 
   virtual void GlobalPreferencesUpdated()
   {
   }
 
   virtual void GlobalFiltersUpdated()
   {
   }
 
   IsoString SettingsKey() const
   {
      return IsoString( "Interfaces/" ) + Id() + '/';
   }
 
   virtual void SaveSettings() const
   {
   }
 
   virtual void LoadSettings()
   {
   }
 
   void SaveGeometry() const;
 
   bool RestoreGeometry();
 
   void SetDefaultPosition();
 
   bool IsAutoSaveGeometryEnabled() const
   {
      return m_autoSaveGeometry;
   }
 
   void EnableAutoSaveGeometry( bool enable = true )
   {
      m_autoSaveGeometry = enable;
   }
 
   void DisableAutoSaveGeometry( bool disable = true )
   {
      EnableAutoSaveGeometry( !disable );
   }
 
   static void BroadcastImageUpdated( const View& view );
 
   static void ProcessEvents( bool excludeUserInputEvents = false );
 
protected:
 
   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 2024-06-18T15:48:54Z