PCL
Public Member Functions | Static Public Member Functions | List of all members
pcl::ProcessInterface Class Referenceabstract

Client-side interface to a PixInsight process interface window. More...

#include <ProcessInterface.h>

+ Inheritance diagram for pcl::ProcessInterface:

Public Member Functions

 ProcessInterface ()
 
 ~ProcessInterface () noexcept(false) override
 
virtual IsoString Aliases () const
 
virtual void ApplyInstance () const
 
virtual void ApplyInstanceGlobal () const
 
virtual void BeginReadout (const View &view)
 
virtual bool BrowseDocumentation () const
 
virtual void Cancel ()
 
virtual void CancelRealTimePreview ()
 
virtual bool CanImportInstances () const
 
virtual String Description () const
 
void DisableAutoSaveGeometry (bool disable=true)
 
virtual bool DistinguishesTestInstances () const
 
virtual bool DynamicKeyPress (View &view, int key, unsigned modifiers)
 
virtual bool DynamicKeyRelease (View &view, int key, unsigned modifiers)
 
virtual void DynamicMouseDoubleClick (View &view, const DPoint &cursorPos, unsigned buttons, unsigned modifiers)
 
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 bool DynamicMouseWheel (View &view, const DPoint &cursorPos, int wheelDelta, unsigned buttons, unsigned modifiers)
 
virtual void DynamicPaint (const View &view, VectorGraphics &graphics, const DRect &rect) const
 
virtual void EditPreferences ()
 
void EnableAutoSaveGeometry (bool enable=true)
 
virtual void EndReadout (const View &view)
 
virtual bool EnterDynamicMode ()
 
virtual void Execute ()
 
virtual void ExitDynamicMode ()
 
virtual InterfaceFeatures Features () const
 
virtual bool GenerateRealTimePreview (UInt16Image &image, const View &view, const Rect &rect, int zoomLevel, String &info) const
 
virtual void GlobalCMDisabled ()
 
virtual void GlobalCMEnabled ()
 
virtual void GlobalCMUpdated ()
 
virtual void GlobalFiltersUpdated ()
 
virtual void GlobalPreferencesUpdated ()
 
virtual void GlobalRGBWSUpdated ()
 
virtual String IconImageFile () const
 
virtual IsoString IconImageSVG () const
 
virtual String IconImageSVGFile () const
 
virtual const char ** IconImageXPM () const
 
virtual IsoString Id () const =0
 
virtual void ImageCMDisabled (const View &view)
 
virtual void ImageCMEnabled (const View &view)
 
virtual void ImageCMUpdated (const View &view)
 
virtual void ImageCreated (const View &view)
 
virtual void ImageDeleted (const View &view)
 
virtual void ImageFocused (const View &view)
 
virtual void ImageLocked (const View &view)
 
virtual void ImageRenamed (const View &view)
 
virtual void ImageRGBWSUpdated (const View &view)
 
virtual void ImageSaved (const View &view)
 
virtual void ImageSTFDisabled (const View &view)
 
virtual void ImageSTFEnabled (const View &view)
 
virtual void ImageSTFUpdated (const View &view)
 
virtual void ImageUnlocked (const View &view)
 
virtual void ImageUpdated (const View &view)
 
virtual bool ImportProcess (const ProcessImplementation &)
 
virtual void Initialize ()
 
bool IsAutoSaveGeometryEnabled () const
 
virtual bool IsDynamicInterface () const
 
virtual bool IsInstanceGenerator () const
 
virtual bool Launch (const MetaProcess &process, const ProcessImplementation *instance, bool &dynamic, unsigned &flags)
 
bool Launch (unsigned flags=0)
 
size_type LaunchCount () const
 
virtual void LoadSettings ()
 
virtual void MaskDisabled (const View &view)
 
virtual void MaskEnabled (const View &view)
 
virtual void MaskHidden (const View &view)
 
virtual void MaskShown (const View &view)
 
virtual void MaskUpdated (const View &view)
 
virtual ProcessImplementation * NewProcess () const
 
virtual ProcessImplementation * NewTestProcess () const
 
virtual MetaProcess * Process () const =0
 
virtual void ProcessCreated (const ProcessInstance &instance)
 
virtual void ProcessDeleted (const ProcessInstance &instance)
 
virtual void ProcessSaved (const ProcessInstance &instance)
 
virtual void ProcessUpdated (const ProcessInstance &instance)
 
virtual void ReadoutOptionsUpdated ()
 
virtual void RealTimePreviewGenerationFinished ()
 
virtual pcl::RealTimePreviewGenerationFlags RealTimePreviewGenerationFlags (UInt16Image &image, const View &view, const Rect &rect, int zoomLevel) const
 
virtual void RealTimePreviewGenerationStarted ()
 
virtual void RealTimePreviewLUTUpdated (int colorModel)
 
virtual void RealTimePreviewOwnerChanged (ProcessInterface &iface)
 
virtual void RealTimePreviewUpdated (bool active)
 
virtual bool RequiresDynamicUpdate (const View &view, const DRect &rect) const
 
virtual bool RequiresInstanceValidation () const
 
virtual bool RequiresRealTimePreviewUpdate (const UInt16Image &image, const View &view, const Rect &rect, int zoomLevel) const
 
virtual void ResetInstance ()
 
bool RestoreGeometry ()
 
void SaveGeometry () const
 
virtual void SaveSettings () const
 
void SetDefaultPosition ()
 
IsoString SettingsKey () const
 
virtual String SmallIconImageFile () const
 
virtual const char ** SmallIconImageXPM () const
 
virtual void TrackViewUpdated (bool active)
 
virtual void TransparencyHidden (const View &view)
 
virtual void TransparencyModeUpdated (const View &view)
 
virtual void UpdateReadout (const View &view, const DPoint &position, double R, double G, double B, double A)
 
virtual bool ValidateProcess (const ProcessImplementation &instance, String &whyNot) const
 
virtual uint32 Version () const
 
virtual void ViewPropertyDeleted (const View &view, const IsoString &property)
 
virtual void ViewPropertyUpdated (const View &view, const IsoString &property)
 
virtual bool WantsGlobalNotifications () const
 
virtual bool WantsImageNotifications () const
 
virtual bool WantsMaskNotifications () const
 
virtual bool WantsProcessNotifications () const
 
virtual bool WantsReadoutNotifications () const
 
virtual bool WantsRealTimePreviewNotifications () const
 
virtual bool WantsTransparencyNotifications () const
 
virtual bool WantsViewPropertyNotifications () const
 
- Public Member Functions inherited from pcl::Control
 Control (const Control &)=delete
 
 Control (Control &&)=delete
 
 Control (Control &parent=Null(), uint32=0)
 
 ~Control () override
 
void ActivateRealTimePreview ()
 
void ActivateTrackView ()
 
void ActivateWindow ()
 
void AdjustToContents ()
 
RGBA AlternateCanvasColor () const
 
RGBA BackgroundColor () const
 
pcl::Rect BoundsRect () const
 
void BringToFront ()
 
RGBA ButtonColor () const
 
RGBA ButtonTextColor () const
 
bool CanUpdate () const
 
RGBA CanvasColor ()
 
Control & ChildByPos (const pcl::Point &p) const
 
Control & ChildByPos (int x, int y) const
 
pcl::Rect ChildrenRect () const
 
Control & ChildToFocus () const
 
void ClearInfoText ()
 
int ClientHeight () const
 
pcl::Rect ClientRect () const
 
int ClientWidth () const
 
void ControlToLocal (const Control &, int &x, int &y) const
 
pcl::Point ControlToLocal (const Control &w, const pcl::Point &p) const
 
pcl::Cursor Cursor () const
 
void DeactivateRealTimePreview ()
 
void DeactivateTrackView ()
 
void Disable (bool disabled=true)
 
void DisableExpansion (bool horzDisable=true, bool vertDisable=true)
 
void DisableMouseTracking (bool disable=true)
 
void DisableUpdates (bool disable=true)
 
double DisplayPixelRatio () const
 
virtual void Enable (bool enabled=true)
 
void EnableExpansion (bool horzEnable=true, bool vertEnable=true)
 
void EnableMouseTracking (bool=true)
 
void EnableUpdates (bool enable=true)
 
void EnsureLayoutUpdated ()
 
void EnsureUnique () override
 
void Focus (bool focus=true)
 
Control & FocusedChild () const
 
FocusStyles FocusStyle () const
 
pcl::Font Font () const
 
RGBA ForegroundColor () const
 
int FrameHeight () const
 
pcl::Rect FrameRect () const
 
int FrameWidth () const
 
pcl::Cursor GetCursor () const
 
pcl::Font GetFont () const
 
void GetMaxSize (int &w, int &h) const
 
void GetMinSize (int &w, int &h) const
 
void GetScaledMaxSize (int &w, int &h) const
 
void GetScaledMinSize (int &w, int &h) const
 
pcl::Sizer GetSizer () const
 
pcl::Point GlobalToLocal (const pcl::Point &p) const
 
void GlobalToLocal (int &x, int &y) const
 
int Height () const
 
void Hide ()
 
RGBA HighlightColor () const
 
RGBA HighlightedTextColor () const
 
String InfoText () const
 
bool IsActiveWindow () const
 
bool IsAncestorOf (const Control &) const
 
virtual bool IsEnabled () const
 
bool IsFixedHeight () const
 
bool IsFixedWidth () const
 
bool IsFocused () const
 
bool IsHidden () const
 
bool IsHorizontalExpansionEnabled () const
 
bool IsMaximized () const
 
bool IsMinimized () const
 
bool IsModal () const
 
bool IsMouseTrackingEnabled () const
 
bool IsRealTimePreviewActive () const
 
bool IsTrackViewActive () const
 
bool IsUnderMouse () const
 
bool IsVerticalExpansionEnabled () const
 
bool IsVisible () const
 
bool IsWindow () const
 
void LocalToControl (const Control &, int &x, int &y) const
 
pcl::Point LocalToControl (const Control &w, const pcl::Point &p) const
 
pcl::Point LocalToGlobal (const pcl::Point &p) const
 
void LocalToGlobal (int &x, int &y) const
 
pcl::Point LocalToParent (const pcl::Point &p) const
 
void LocalToParent (int &x, int &y) const
 
int LogicalPixelsToPhysical (int size) const
 
int LogicalPixelsToResource (int size) const
 
int MaxHeight () const
 
int MaxWidth () const
 
int MinHeight () const
 
int MinWidth () const
 
void Move (const pcl::Point &p)
 
void Move (int x, int y)
 
Control & NextSiblingToFocus () const
 
void OnChildCreate (child_event_handler, Control &)
 
void OnChildDestroy (child_event_handler, Control &)
 
void OnClose (close_event_handler, Control &)
 
void OnDestroy (event_handler, Control &)
 
void OnEnter (event_handler, Control &)
 
void OnFileDrag (file_drag_event_handler, Control &)
 
void OnFileDrop (file_drop_event_handler, Control &)
 
void OnGetFocus (event_handler, Control &)
 
void OnHide (event_handler, Control &)
 
void OnKeyPress (keyboard_event_handler, Control &)
 
void OnKeyRelease (keyboard_event_handler, Control &)
 
void OnLeave (event_handler, Control &)
 
void OnLoseFocus (event_handler, Control &)
 
void OnMouseDoubleClick (mouse_event_handler, Control &)
 
void OnMouseMove (mouse_event_handler, Control &)
 
void OnMousePress (mouse_button_event_handler, Control &)
 
void OnMouseRelease (mouse_button_event_handler, Control &)
 
void OnMouseWheel (mouse_wheel_event_handler, Control &)
 
void OnMove (move_event_handler, Control &)
 
void OnPaint (paint_event_handler, Control &)
 
void OnResize (resize_event_handler, Control &)
 
void OnShow (event_handler, Control &)
 
void OnViewDrag (view_drag_event_handler, Control &)
 
void OnViewDrop (view_drop_event_handler, Control &)
 
Control & operator= (const Control &)=delete
 
Control & operator= (Control &&)=delete
 
Control & Parent () const
 
pcl::Point ParentToLocal (const pcl::Point &p) const
 
void ParentToLocal (int &x, int &y) const
 
int PhysicalPixelsToLogical (int size) const
 
pcl::Point Position () const
 
void Repaint ()
 
void Repaint (const pcl::Rect &r)
 
void Repaint (int x0, int y0, int x1, int y1)
 
void Resize (int w, int h)
 
double ResourcePixelRatio () const
 
int ResourcePixelsToLogical (int size) const
 
void Restyle ()
 
Point ScaledCursorHotSpot (const Point &hotSpot) const
 
Point ScaledCursorHotSpot (int xHot, int yHot) const
 
int ScaledMaxHeight () const
 
int ScaledMaxWidth () const
 
int ScaledMinHeight () const
 
int ScaledMinWidth () const
 
template<class R >
String ScaledResource (R resource) const
 
template<class S >
String ScaledStyleSheet (S cssCode, int fontDPI=0) const
 
void Scroll (const pcl::Point &d)
 
void Scroll (const pcl::Point &d, const pcl::Rect &r)
 
void Scroll (int dx, int dy)
 
void Scroll (int dx, int dy, int x0, int y0, int x1, int y1)
 
void SendToBack ()
 
void SetAlternateCanvasColor (RGBA)
 
void SetBackgroundColor (RGBA)
 
void SetButtonColor (RGBA)
 
void SetButtonTextColor (RGBA)
 
void SetCanvasColor (RGBA)
 
void SetChildToFocus (Control &)
 
void SetClientRect (const pcl::Rect &r)
 
void SetClientRect (int x0, int y0, int x1, int y1)
 
void SetCursor (const pcl::Cursor &)
 
void SetCursorToParent ()
 
void SetFixedHeight ()
 
void SetFixedHeight (int h)
 
void SetFixedSize ()
 
void SetFixedSize (int w, int h)
 
void SetFixedWidth ()
 
void SetFixedWidth (int w)
 
void SetFocusStyle (FocusStyles)
 
void SetFont (const pcl::Font &)
 
void SetForegroundColor (RGBA)
 
void SetHighlightColor (RGBA)
 
void SetHighlightedTextColor (RGBA)
 
void SetInfoText (const String &)
 
void SetMaxHeight ()
 
void SetMaxHeight (int h)
 
void SetMaxSize ()
 
void SetMaxSize (int w, int h)
 
void SetMaxWidth ()
 
void SetMaxWidth (int w)
 
void SetMinHeight ()
 
void SetMinHeight (int h)
 
void SetMinSize ()
 
void SetMinSize (int w, int h)
 
void SetMinWidth ()
 
void SetMinWidth (int w)
 
void SetNextSiblingToFocus (Control &)
 
void SetParent (Control &)
 
void SetRealTimePreviewActive (bool=true)
 
void SetScaledFixedHeight (int h)
 
void SetScaledFixedSize (int w, int h)
 
void SetScaledFixedWidth (int w)
 
void SetScaledMaxHeight (int h)
 
void SetScaledMaxSize (int w, int h)
 
void SetScaledMaxWidth (int w)
 
void SetScaledMinHeight (int h)
 
void SetScaledMinSize (int w, int h)
 
void SetScaledMinWidth (int w)
 
void SetSizer (pcl::Sizer &)
 
void SetStyleSheet (const String &css)
 
void SetTextColor (RGBA)
 
void SetToolTip (const String &)
 
void SetTrackViewActive (bool=true)
 
void SetVariableHeight ()
 
void SetVariableSize ()
 
void SetVariableWidth ()
 
void SetVisible (bool visible)
 
void SetWindowOpacity (double)
 
void SetWindowTitle (const String &)
 
void Show ()
 
pcl::Sizer Sizer () const
 
void StackUnder (Control &)
 
String StyleSheet () const
 
RGBA TextColor () const
 
String ToolTip () const
 
void Unfocus ()
 
void Update ()
 
void Update (const pcl::Rect &r)
 
void Update (int x0, int y0, int x1, int y1)
 
pcl::Rect VisibleRect () const
 
int Width () const
 
Control & Window () const
 
double WindowOpacity () const
 
String WindowTitle () const
 
int X () const
 
int Y () const
 
- Public Member Functions inherited from pcl::UIObject
virtual ~UIObject () noexcept(false)
 
bool IsAlias () const
 
bool IsGarbage () const
 
bool IsNull () const
 
bool IsSameObject (const UIObject &o) const
 
bool IsUnique () const
 
String ObjectId () const
 
IsoString ObjectType () const
 
bool operator< (const UIObject &o) const
 
bool operator== (const UIObject &o) const
 
size_type RefCount () const
 
void SetObjectId (const String &id)
 
- Public Member Functions inherited from pcl::MetaObject
 MetaObject (const MetaObject &)=delete
 
 MetaObject (MetaObject &&x)=delete
 
 MetaObject (MetaObject *parent)
 
virtual ~MetaObject () noexcept(false)
 
size_type Length () const
 
MetaObject & operator= (const MetaObject &)=delete
 
MetaObject & operator= (MetaObject &&x)=delete
 
const MetaObject * operator[] (size_type i) const
 
MetaObject * Parent ()
 
const MetaObject * Parent () const
 

Static Public Member Functions

static void BroadcastImageUpdated (const View &view)
 
static ProcessInterface & Null ()
 
static void ProcessEvents (bool excludeUserInputEvents=false)
 
- Static Public Member Functions inherited from pcl::Control
static void HideToolTip ()
 
static Control & Null ()
 
static void ShowToolTip (const Point &pos, const String &text, const Control &control=Control::Null(), const Rect &rect=Rect(0))
 
static void ShowToolTip (int x, int y, const String &text, const Control &control=Control::Null(), const Rect &rect=Rect(0))
 
static String ToolTipText ()
 
- Static Public Member Functions inherited from pcl::UIObject
static UIObject & Null ()
 

Additional Inherited Members

- Public Types inherited from pcl::Control
using child_event_handler = void(Control::*)(Control &sender, Control &child)
 
using close_event_handler = void(Control::*)(Control &sender, bool &allowClose)
 
using event_handler = void(Control::*)(Control &sender)
 
using file_drag_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, const StringList &files, unsigned modifiers, bool &wantsFiles)
 
using file_drop_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, const StringList &files, unsigned modifiers)
 
using keyboard_event_handler = void(Control::*)(Control &sender, int key, unsigned modifiers, bool &wantsKey)
 
using mouse_button_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, int button, unsigned buttons, unsigned modifiers)
 
using mouse_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, unsigned buttons, unsigned modifiers)
 
using mouse_wheel_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, int delta, unsigned buttons, unsigned modifiers)
 
using move_event_handler = void(Control::*)(Control &sender, const pcl::Point &newPos, const pcl::Point &oldPos)
 
using paint_event_handler = void(Control::*)(Control &sender, const pcl::Rect &updateRect)
 
using resize_event_handler = void(Control::*)(Control &sender, int newWidth, int newHeight, int oldWidth, int oldHeight)
 
using view_drag_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, const View &view, unsigned modifiers, bool &wantsView)
 
using view_drop_event_handler = void(Control::*)(Control &sender, const pcl::Point &pos, const View &view, unsigned modifiers)
 
- Public Types inherited from pcl::MetaObject
using children_list = IndirectArray< MetaObject >
 
- Protected Member Functions inherited from pcl::UIObject
 UIObject ()=default
 
 UIObject (const UIObject &x)
 
 UIObject (UIObject &&x)
 
UIObject & operator= (const UIObject &x)
 
UIObject & operator= (UIObject &&x)
 

Detailed Description

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.

Definition at line 255 of file ProcessInterface.h.

Constructor & Destructor Documentation

◆ ProcessInterface()

pcl::ProcessInterface::ProcessInterface ( )

Constructs a process interface window.

◆ ~ProcessInterface()

pcl::ProcessInterface::~ProcessInterface ( )
inlineoverridenoexcept

Destroys a ProcessInterface object.

Definition at line 267 of file ProcessInterface.h.

Member Function Documentation

◆ Aliases()

virtual IsoString pcl::ProcessInterface::Aliases ( ) const
inlinevirtual

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).
See also
Id()

Definition at line 315 of file ProcessInterface.h.

◆ ApplyInstance()

virtual void pcl::ProcessInterface::ApplyInstance ( ) const
virtual

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.

◆ ApplyInstanceGlobal()

virtual void pcl::ProcessInterface::ApplyInstanceGlobal ( ) const
virtual

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.

◆ BroadcastImageUpdated()

static void pcl::ProcessInterface::BroadcastImageUpdated ( const View &  view)
static

Issues an ImageUpdated notification for a view.

Parameters
viewReference 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 not be used on a regular basis without having a 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 because of excessive overhead.

◆ BrowseDocumentation()

virtual bool pcl::ProcessInterface::BrowseDocumentation ( ) const
virtual

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:

const MetaProcess* P = Process();
if ( P != nullptr )
if ( P->CanBrowseDocumentation() )
P->BrowseDocumentation();
pcl::ProcessInterface::Process
virtual MetaProcess * Process() const =0

In general, a derived class should not need to reimplement this member function, as the default behavior is appropriate in most cases.

◆ Cancel()

virtual void pcl::ProcessInterface::Cancel ( )
virtual

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.

◆ CancelRealTimePreview()

virtual void pcl::ProcessInterface::CancelRealTimePreview ( )
inlinevirtual

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.

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.
See also
GenerateRealTimePreview()

Definition at line 1293 of file ProcessInterface.h.

◆ CanImportInstances()

virtual bool pcl::ProcessInterface::CanImportInstances ( ) const
inlinevirtual

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.
See also
ImportProcess()

Definition at line 1110 of file ProcessInterface.h.

◆ Description()

virtual String pcl::ProcessInterface::Description ( ) const
inlinevirtual

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.

Definition at line 358 of file ProcessInterface.h.

◆ DisableAutoSaveGeometry()

void pcl::ProcessInterface::DisableAutoSaveGeometry ( bool  disable = true)
inline

Disables the auto save geometry feature. For more information on this feature, see the documentation for the IsAutoSaveGeometryEnabled() member function.

See also
EnableAutoSaveGeometry(), IsAutoSaveGeometryEnabled()

Definition at line 2613 of file ProcessInterface.h.

◆ DistinguishesTestInstances()

virtual bool pcl::ProcessInterface::DistinguishesTestInstances ( ) const
inlinevirtual

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 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.
See also
NewTestProcess()

Definition at line 1007 of file ProcessInterface.h.

◆ DynamicKeyPress()

virtual bool pcl::ProcessInterface::DynamicKeyPress ( View &  view,
int  key,
unsigned  modifiers 
)
inlinevirtual

Function called if a key is pressed when a view has the keyboard focus, during an active dynamic session.

Parameters
viewReference to the view that had the keyboard focus when a key was pressed.
keyA KeyCode code identifying the keyboard key that has been pressed.
modifiersIndicates 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.
See also
DynamicKeyRelease()

Definition at line 1515 of file ProcessInterface.h.

◆ DynamicKeyRelease()

virtual bool pcl::ProcessInterface::DynamicKeyRelease ( View &  view,
int  key,
unsigned  modifiers 
)
inlinevirtual

Function called if a key is released when a view has the keyboard focus, during an active dynamic session.

Parameters
viewReference to the view that had the keyboard focus when a key was released.
keyA KeyCode code identifying the keyboard key that has been released.
modifiersIndicates 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.
See also
DynamicKeyPress()

Definition at line 1542 of file ProcessInterface.h.

◆ DynamicMouseDoubleClick()

virtual void pcl::ProcessInterface::DynamicMouseDoubleClick ( View &  view,
const DPoint &  cursorPos,
unsigned  buttons,
unsigned  modifiers 
)
inlinevirtual

Function called when the primary mouse button is double-clicked on a view, during an active dynamic session.

Parameters
viewReference to a view over which the primary mouse button has been double-clicked.
cursorPosCurrent mouse cursor position in image coordinates.
buttonsIndicates 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.
modifiersIndicates 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.
See also
DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), DynamicMousePress(), DynamicMouseRelease(), DynamicMouseWheel()

Definition at line 1488 of file ProcessInterface.h.

◆ DynamicMouseEnter()

virtual void pcl::ProcessInterface::DynamicMouseEnter ( View &  view)
inlinevirtual

Function called when the mouse cursor enters the viewport of a view, during an active dynamic session.

Note
The default implementation of this function does nothing.
See also
DynamicMouseLeave(), DynamicMouseMove(), DynamicMousePress(), DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel()

Definition at line 1362 of file ProcessInterface.h.

◆ DynamicMouseLeave()

virtual void pcl::ProcessInterface::DynamicMouseLeave ( View &  view)
inlinevirtual

Function called when the mouse cursor leaves the viewport of a view, during an active dynamic session.

Note
The default implementation of this function does nothing.
See also
DynamicMouseEnter(), DynamicMouseMove(), DynamicMousePress(), DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel()

Definition at line 1375 of file ProcessInterface.h.

◆ DynamicMouseMove()

virtual void pcl::ProcessInterface::DynamicMouseMove ( View &  view,
const DPoint &  cursorPos,
unsigned  buttons,
unsigned  modifiers 
)
inlinevirtual

Function called when the mouse cursor is displaced on a view, during an active dynamic session.

Parameters
viewReference to a view over which the mouse cursor has been displaced.
cursorPosNew mouse cursor position in image coordinates.
buttonsIndicates 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.
modifiersIndicates 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.
See also
DynamicMouseEnter(), DynamicMouseLeave(), DynamicMousePress(), DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel()

Definition at line 1401 of file ProcessInterface.h.

◆ DynamicMousePress()

virtual void pcl::ProcessInterface::DynamicMousePress ( View &  view,
const DPoint &  cursorPos,
int  button,
unsigned  buttons,
unsigned  modifiers 
)
inlinevirtual

Function called when a mouse button is pressed on a view, during an active dynamic session.

Parameters
viewReference to a view over which a mouse button has been pressed.
cursorPosCurrent mouse cursor position in image coordinates.
buttonIdentifies the mouse button that has been pressed. This value is a unique MouseButton flag.
buttonsIndicates 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.
modifiersIndicates 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.
See also
DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), DynamicMouseRelease(), DynamicMouseDoubleClick(), DynamicMouseWheel()

Definition at line 1431 of file ProcessInterface.h.

◆ DynamicMouseRelease()

virtual void pcl::ProcessInterface::DynamicMouseRelease ( View &  view,
const DPoint &  cursorPos,
int  button,
unsigned  buttons,
unsigned  modifiers 
)
inlinevirtual

Function called when a mouse button is released on a view, during an active dynamic session.

Parameters
viewReference to a view over which a mouse button has been released.
cursorPosCurrent mouse cursor position in image coordinates.
buttonIdentifies the mouse button that has been released. This value is a unique MouseButton flag.
buttonsIndicates 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.
modifiersIndicates 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.
See also
DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), DynamicMousePress(), DynamicMouseDoubleClick(), DynamicMouseWheel()

Definition at line 1461 of file ProcessInterface.h.

◆ DynamicMouseWheel()

virtual bool pcl::ProcessInterface::DynamicMouseWheel ( View &  view,
const DPoint &  cursorPos,
int  wheelDelta,
unsigned  buttons,
unsigned  modifiers 
)
inlinevirtual

Function called when the mouse wheel is rotated while the mouse cursor is over a view, during an active dynamic session.

Parameters
viewReference to a view over which the mouse cursor was located when the mouse wheel was rotated.
cursorPosCurrent mouse cursor position in image coordinates.
wheelDeltaWheel 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.
buttonsIndicates 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.
modifiersIndicates 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.
See also
DynamicMouseEnter(), DynamicMouseLeave(), DynamicMouseMove(), DynamicMousePress(), DynamicMouseRelease(), DynamicMouseDoubleClick()

Definition at line 1580 of file ProcessInterface.h.

◆ DynamicPaint()

virtual void pcl::ProcessInterface::DynamicPaint ( const View &  view,
VectorGraphics &  graphics,
const DRect &  rect 
) const
inlinevirtual

Function called when a view's screen rendition has been updated.

Parameters
viewReference to a view where the specified update region should be redrawn by this interface.
graphicsReference to a vector graphics context, where all screen drawing work must be performed.
rectUpdate region in image coordinates.

This function 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 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 after this function returns.

When this function is called, the update region has already been set as the current clipping region of the 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 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.
See also
RequiresDynamicUpdate(), VectorGraphics

Definition at line 1647 of file ProcessInterface.h.

◆ EditPreferences()

virtual void pcl::ProcessInterface::EditPreferences ( )
inlinevirtual

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.
See also
MetaProcess::CanEditPreferences(), MetaProcess::EditPreferences()

Definition at line 724 of file ProcessInterface.h.

◆ EnableAutoSaveGeometry()

void pcl::ProcessInterface::EnableAutoSaveGeometry ( bool  enable = true)
inline

Enables the auto save geometry feature. For more information on this feature, see the documentation for the IsAutoSaveGeometryEnabled() member function.

See also
DisableAutoSaveGeometry(), IsAutoSaveGeometryEnabled()

Definition at line 2601 of file ProcessInterface.h.

◆ EnterDynamicMode()

virtual bool pcl::ProcessInterface::EnterDynamicMode ( )
inlinevirtual

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.
See also
ExitDynamicMode()

Definition at line 1337 of file ProcessInterface.h.

◆ Execute()

virtual void pcl::ProcessInterface::Execute ( )
inlinevirtual

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.

Definition at line 612 of file ProcessInterface.h.

◆ ExitDynamicMode()

virtual void pcl::ProcessInterface::ExitDynamicMode ( )
inlinevirtual

Function called just after a dynamic session has been terminated.

Note
The default implementation of this function does nothing.
See also
EnterDynamicMode()

Definition at line 1349 of file ProcessInterface.h.

◆ Features()

virtual InterfaceFeatures pcl::ProcessInterface::Features ( ) const
inlinevirtual

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.
See also
InterfaceFeature

Definition at line 564 of file ProcessInterface.h.

◆ GenerateRealTimePreview()

virtual bool pcl::ProcessInterface::GenerateRealTimePreview ( UInt16Image &  image,
const View &  view,
const Rect &  rect,
int  zoomLevel,
String &  info 
) const
inlinevirtual

Function called to generate a new real-time preview rendition.

Parameters
[in,out]imageReference 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.
viewReference to a view that is currently selected in the Real-Time Preview system of the core application. The passed image contains a representation of the image in this view.
rectCurrent real-time region in view image coordinates. If a nonempty rectangle is received through this parameter, then the input image contains a representation of the corresponding rectangular region of the view's image. If this parameter is an empty rectangle, it must be ignored and image is a representation of the entire view's image.
zoomLevelIndicates the integer zoom ratio that has been applied to the specified 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 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 image corresponds to one source pixel. In other words, real-time preview images can be scaled down, but are never magnified or scaled up.
[out]infoReference 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 (zoomLevel) does not allow a reasonably accurate representation of some process features.

This function will only be invoked when this interface is the owner of the Real-Time Preview system.

Returns true to signal that the passed image has been modified and can now be used to update the current real-time preview. Returns false to indicate that the image has not been altered by this function, and hence that the current real-time preview update can be aborted or simplified as appropriate.

The passed view and 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 image.
See also
RequiresRealTimePreviewUpdate(), RealTimePreviewGenerationFlags(), CancelRealTimePreview(), RealTimePreview::ShowProgressDialog(), RealTimePreview

Definition at line 1266 of file ProcessInterface.h.

◆ IconImageFile()

virtual String pcl::ProcessInterface::IconImageFile ( ) const
inlinevirtual

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.
See also
IconImageXPM()

Definition at line 487 of file ProcessInterface.h.

◆ IconImageSVG()

virtual IsoString pcl::ProcessInterface::IconImageSVG ( ) const
inlinevirtual

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.
See also
IconImageSVGFile()

Definition at line 390 of file ProcessInterface.h.

◆ IconImageSVGFile()

virtual String pcl::ProcessInterface::IconImageSVGFile ( ) const
inlinevirtual

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.
See also
IconImageSVG()

Definition at line 429 of file ProcessInterface.h.

◆ IconImageXPM()

virtual const char** pcl::ProcessInterface::IconImageXPM ( ) const
inlinevirtual

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.
See also
IconImageFile()

Definition at line 461 of file ProcessInterface.h.

◆ Id()

virtual IsoString pcl::ProcessInterface::Id ( ) const
pure virtual

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, FastRotation is used as the identifier of the FastRotation process and its interface window.

◆ ImportProcess()

virtual bool pcl::ProcessInterface::ImportProcess ( const ProcessImplementation &  )
inlinevirtual

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.
See also
ValidateProcess(), CanImportInstances(), ProcessImplementation::SelectInterface()

Definition at line 1095 of file ProcessInterface.h.

◆ Initialize()

virtual void pcl::ProcessInterface::Initialize ( )
inlinevirtual

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 deferred 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.
See also
Launch( const MetaProcess&, const ProcessImplementation*, bool&, unsigned& ), Launch( unsigned )

Definition at line 767 of file ProcessInterface.h.

◆ IsAutoSaveGeometryEnabled()

bool pcl::ProcessInterface::IsAutoSaveGeometryEnabled ( ) const
inline

Returns true iff the auto save geometry feature is currently active for this interface.

When auto save geometry is active, the interface 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.
See also
EnableAutoSaveGeometry(), DisableAutoSaveGeometry(), SaveGeometry(), RestoreGeometry(), SetDefaultPosition()

Definition at line 2589 of file ProcessInterface.h.

◆ IsDynamicInterface()

virtual bool pcl::ProcessInterface::IsDynamicInterface ( ) const
inlinevirtual

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.
See also
Launch()

Definition at line 1323 of file ProcessInterface.h.

◆ IsInstanceGenerator()

virtual bool pcl::ProcessInterface::IsInstanceGenerator ( ) const
inlinevirtual

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 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.
See also
NewProcess()

Definition at line 979 of file ProcessInterface.h.

◆ Launch() [1/2]

virtual bool pcl::ProcessInterface::Launch ( const MetaProcess &  process,
const ProcessImplementation *  instance,
bool &  dynamic,
unsigned &  flags 
)
inlinevirtual

Process interface launch routine.

Parameters
processReference to the metaprocess describing the process class that is launching this interface, either directly as its default interface, or through an existing process instance.
instanceAddress 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 process.
[out]dynamicTrue if this interface wants to be launched in dynamic mode; false if this interface will launch as a static interface.
flagsReserved for future extensions - must not be modified.

This function is called whenever an interface is about to be 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 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 dynamic referenced argument variable must be set to 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 dynamic = false and returns true, so all process interfaces are static by default.
See also
Initialize(), LaunchCount(), Launch( unsigned )

Definition at line 842 of file ProcessInterface.h.

◆ Launch() [2/2]

bool pcl::ProcessInterface::Launch ( unsigned  flags = 0)

Launches this interface with its default process.

Parameters
flagsReserved 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:

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 );
}
pcl::ProcessInterface::Launch
virtual bool Launch(const MetaProcess &process, const ProcessImplementation *instance, bool &dynamic, unsigned &flags)
Definition: ProcessInterface.h:842
See also
Launch( const MetaProcess&, const ProcessImplementation*, bool&, unsigned& ),

◆ LaunchCount()

size_type pcl::ProcessInterface::LaunchCount ( ) const
inline

Returns the number of times this interface has been launched since the beginning of the current PixInsight session.

See also
Launch()

Definition at line 881 of file ProcessInterface.h.

◆ LoadSettings()

virtual void pcl::ProcessInterface::LoadSettings ( )
inlinevirtual

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:

IsoString key = SettingsKey() + "Geometry/";
// ...
Settings::Write( key + "Width", Width() );
pcl::Control::Width
int Width() const
Definition: Control.h:224
pcl::ProcessInterface::SettingsKey
IsoString SettingsKey() const
Definition: ProcessInterface.h:2455
pcl::Settings::Write
static void Write(const IsoString &key, const ByteArray &b)

would save the current width of this interface to the "Interfaces/&lt;id&gt;/Geometry/Width" subkey in the global settings space assigned to the current module. This is the recommended behavior.

See also
Settings, SaveSettings(), SettingsKey()

Definition at line 2508 of file ProcessInterface.h.

◆ NewProcess()

virtual ProcessImplementation* pcl::ProcessInterface::NewProcess ( ) const
inlinevirtual

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 arbitrary instances that have no logical connection with the 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 mandatory that the interface reimplements the IsInstanceGenerator() member function to return false.
See also
IsInstanceGenerator(), NewTestProcess(), MetaProcess::Clone()

Definition at line 914 of file ProcessInterface.h.

◆ NewTestProcess()

virtual ProcessImplementation* pcl::ProcessInterface::NewTestProcess ( ) const
inlinevirtual

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 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().
See also
DistinguishesTestInstances(), NewProcess(), MetaProcess::TestClone()

Definition at line 955 of file ProcessInterface.h.

◆ Null()

static ProcessInterface& pcl::ProcessInterface::Null ( )
static

Returns a reference to a null ProcessInterface instance. A null ProcessInterface does not correspond to an existing interface window in the PixInsight core application.

◆ Process()

virtual MetaProcess* pcl::ProcessInterface::Process ( ) const
pure virtual

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.

◆ ProcessEvents()

static void pcl::ProcessInterface::ProcessEvents ( bool  excludeUserInputEvents = false)
static

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 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 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.

◆ RealTimePreviewGenerationFlags()

virtual pcl::RealTimePreviewGenerationFlags pcl::ProcessInterface::RealTimePreviewGenerationFlags ( UInt16Image &  image,
const View &  view,
const Rect &  rect,
int  zoomLevel 
) const
inlinevirtual

Function called to retrieve real-time preview generation flags.

This function will only be invoked when this interface is the owner of the Real-Time Preview system.

This function is called by the core application at the beginning of a real-time preview update, just before calling GenerateRealTimePreview(), with the same parameters that will be passed to that function. Use the constants defined in the RealTimePreviewGenerationFlag namespace in a reimplementation of this function if you need to specify real-time preview generation flags.

For information on the parameters of this function, see RequiresRealTimePreviewUpdate(). All the parameters of this function have the same meaning and values.

The passed image, view and rect objects cannot be modified in any way by this function.

Note
The default implementation of this function returns RealTimePreviewGenerationFlag::None.
See also
GenerateRealTimePreview()

Definition at line 1196 of file ProcessInterface.h.

◆ RealTimePreviewUpdated()

virtual void pcl::ProcessInterface::RealTimePreviewUpdated ( bool  active)
inlinevirtual

Function called when the user toggles the pushed state of the Real Time Preview control bar button.

Parameters
activeTrue 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.

Definition at line 649 of file ProcessInterface.h.

◆ RequiresDynamicUpdate()

virtual bool pcl::ProcessInterface::RequiresDynamicUpdate ( const View &  view,
const DRect &  rect 
) const
inlinevirtual

Function called when a view's screen rendition needs to be updated, during an active dynamic session.

Parameters
viewReference to a view that requires a screen update.
rectUpdate region in image coordinates.

This function 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.
See also
DynamicPaint()

Definition at line 1608 of file ProcessInterface.h.

◆ RequiresInstanceValidation()

virtual bool pcl::ProcessInterface::RequiresInstanceValidation ( ) const
inlinevirtual

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().
See also
ValidateProcess(), ImportProcess()

Definition at line 1056 of file ProcessInterface.h.

◆ RequiresRealTimePreviewUpdate()

virtual bool pcl::ProcessInterface::RequiresRealTimePreviewUpdate ( const UInt16Image &  image,
const View &  view,
const Rect &  rect,
int  zoomLevel 
) const
inlinevirtual

Function called when the real-time preview image needs an update.

Parameters
[in,out]imageReference 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.
viewReference to a view that is currently selected in the Real-Time Preview system of the core application. The passed image contains a representation of the image in this view.
rectCurrent real-time region in view image coordinates. If a nonempty rectangle is received through this parameter, then the input image contains a representation of the corresponding rectangular region of the view's image. If this parameter is an empty rectangle, it must be ignored and image is a representation of the entire view's image.
zoomLevelIndicates the integer zoom ratio that has been applied to the specified 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 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 image corresponds to one source pixel. In other words, real-time preview images can be scaled down, but are never magnified or scaled up.

This function will only be invoked when this interface is the owner of the Real-Time Preview system.

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, subsequent calls to RealTimePreviewGenerationFlags() and GenerateRealTimePreview() will occur in that order when appropriate.

The passed image, view and rect objects cannot be modified in any way by this function.

Note
The default implementation of this function returns false.
See also
GenerateRealTimePreview(), CancelRealTimePreview(), RealTimePreview

Definition at line 1165 of file ProcessInterface.h.

◆ ResetInstance()

virtual void pcl::ProcessInterface::ResetInstance ( )
inlinevirtual

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.

Definition at line 741 of file ProcessInterface.h.

◆ RestoreGeometry()

bool pcl::ProcessInterface::RestoreGeometry ( )

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 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.
See also
SaveGeometry()

◆ SaveGeometry()

void pcl::ProcessInterface::SaveGeometry ( ) const

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
Interfaces/<id>/Geometry/Top
Interfaces/<id>/Geometry/Width
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.
See also
RestoreGeometry(), SetDefaultPosition(), IsAutoSaveGeometryEnabled()

◆ SaveSettings()

virtual void pcl::ProcessInterface::SaveSettings ( ) const
inlinevirtual

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.
See also
Settings, LoadSettings(), SettingsKey()

Definition at line 2480 of file ProcessInterface.h.

◆ SetDefaultPosition()

void pcl::ProcessInterface::SetDefaultPosition ( )

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.

See also
SaveGeometry(), RestoreGeometry()

◆ SettingsKey()

IsoString pcl::ProcessInterface::SettingsKey ( ) const
inline

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/&lt;id&gt;/", 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.
See also
Settings, SaveSettings(), LoadSettings()

Definition at line 2455 of file ProcessInterface.h.

◆ SmallIconImageFile()

virtual String pcl::ProcessInterface::SmallIconImageFile ( ) const
inlinevirtual

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.
See also
SmallIconImageXPM()

Definition at line 546 of file ProcessInterface.h.

◆ SmallIconImageXPM()

virtual const char** pcl::ProcessInterface::SmallIconImageXPM ( ) const
inlinevirtual

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.
See also
SmallIconImageFile()

Definition at line 520 of file ProcessInterface.h.

◆ TrackViewUpdated()

virtual void pcl::ProcessInterface::TrackViewUpdated ( bool  active)
inlinevirtual

Function called when the user toggles the pushed state of the Track View control bar button.

Parameters
activeTrue 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.
See also
Control::IsTrackViewActive(), Control::SetTrackViewActive(), ImageFocused()

Definition at line 702 of file ProcessInterface.h.

◆ ValidateProcess()

virtual bool pcl::ProcessInterface::ValidateProcess ( const ProcessImplementation &  instance,
String &  whyNot 
) const
inlinevirtual

Instance validation function.

Parameters
instanceReference to a process instance that is being validated before being imported by this interface.
[out]whyNotIf this function returns false, it should return also a brief text (256 characters maximum) in this string, explaining why the specified 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.
See also
RequiresInstanceValidation(), ImportProcess()

Definition at line 1037 of file ProcessInterface.h.

References pcl::GenericString< T, R, A >::Clear().

◆ Version()

virtual uint32 pcl::ProcessInterface::Version ( ) const
inlinevirtual

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.

Definition at line 341 of file ProcessInterface.h.

◆ WantsGlobalNotifications()

virtual bool pcl::ProcessInterface::WantsGlobalNotifications ( ) const
inlinevirtual

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.
See also
Global Notification Functions

Definition at line 2357 of file ProcessInterface.h.

◆ WantsImageNotifications()

virtual bool pcl::ProcessInterface::WantsImageNotifications ( ) const
inlinevirtual

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.
See also
Image Notification Functions

Definition at line 1671 of file ProcessInterface.h.

◆ WantsMaskNotifications()

virtual bool pcl::ProcessInterface::WantsMaskNotifications ( ) const
inlinevirtual

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.
See also
Mask Notification Functions

Definition at line 1910 of file ProcessInterface.h.

◆ WantsProcessNotifications()

virtual bool pcl::ProcessInterface::WantsProcessNotifications ( ) const
inlinevirtual

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.
See also
Process Instance Notification Functions

Definition at line 2200 of file ProcessInterface.h.

◆ WantsReadoutNotifications()

virtual bool pcl::ProcessInterface::WantsReadoutNotifications ( ) const
inlinevirtual

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.
See also
Readout Notification Functions

Definition at line 2126 of file ProcessInterface.h.

◆ WantsRealTimePreviewNotifications()

virtual bool pcl::ProcessInterface::WantsRealTimePreviewNotifications ( ) const
inlinevirtual

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.
See also
Real Time Preview Notification Functions

Definition at line 2278 of file ProcessInterface.h.

◆ WantsTransparencyNotifications()

virtual bool pcl::ProcessInterface::WantsTransparencyNotifications ( ) const
inlinevirtual

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.
See also
Image Transparency Notification Functions

Definition at line 2006 of file ProcessInterface.h.

◆ WantsViewPropertyNotifications()

virtual bool pcl::ProcessInterface::WantsViewPropertyNotifications ( ) const
inlinevirtual

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.
See also
View Property Notification Functions

Definition at line 2062 of file ProcessInterface.h.

The documentation for this class was generated from the following file: