PCL
Public Member Functions | Static Public Member Functions | List of all members
pcl::RealTimePreview Class Reference

Client-side interface to the Real-Time Preview system. More...

#include <RealTimePreview.h>

Public Member Functions

 RealTimePreview ()=delete
 
 RealTimePreview (const RealTimePreview &)=delete
 
 ~RealTimePreview ()=delete
 
RealTimePreview & operator= (const RealTimePreview &)=delete
 

Static Public Member Functions

static void CloseProgressDialog ()
 
static bool IsProgressDialogVisible ()
 
static bool IsUpdating ()
 
static bool SetOwner (ProcessInterface &owner)
 
static void SetProgressCount (size_type count)
 
static void SetProgressText (const String &text)
 
static void ShowProgressDialog (const String &title, const String &text, size_type total)
 
static void Update ()
 

Detailed Description

RealTimePreview is a high-level, client-side interface to the Real-Time Preview system available in the PixInsight core application.

Note
The Real-Time Preview system is undergoing extensive development in PixInsight. Be aware that this class will be updated and enhanced considerably in future PCL releases.

Definition at line 82 of file RealTimePreview.h.

Constructor & Destructor Documentation

◆ RealTimePreview() [1/2]

pcl::RealTimePreview::RealTimePreview ( )
delete

Default constructor. This constructor is disabled because RealTimePreview is not an instantiable class.

◆ RealTimePreview() [2/2]

pcl::RealTimePreview::RealTimePreview ( const RealTimePreview &  )
delete

Copy constructor. This constructor is disabled because RealTimePreview is not an instantiable class.

◆ ~RealTimePreview()

pcl::RealTimePreview::~RealTimePreview ( )
delete

Destructor. This destructor is disabled because RealTimePreview is not an instantiable class.

Member Function Documentation

◆ CloseProgressDialog()

static void pcl::RealTimePreview::CloseProgressDialog ( )
static

Requests closing a progress dialog previously shown by a call to ShowProgressDialog().

Referenced by pcl::RealTimeProgressStatus::Completed().

◆ IsProgressDialogVisible()

static bool pcl::RealTimePreview::IsProgressDialogVisible ( )
static

Returns true iff a modal progress dialog is currently visible after a call to ShowProgressDialog().

◆ IsUpdating()

static bool pcl::RealTimePreview::IsUpdating ( )
static

Returns true iff the Real-Time Preview is currently busy, i.e. if there is an active real-time rendition process.

◆ operator=()

RealTimePreview& pcl::RealTimePreview::operator= ( const RealTimePreview &  )
delete

Copy assignment. This operator is disabled because RealTimePreview is not an instantiable class.

◆ SetOwner()

static bool pcl::RealTimePreview::SetOwner ( ProcessInterface &  owner)
static

Sets the owner of the Real-Time Preview interface.

Parameters
ownerReference to a process interface that will own the Real-Time Preview interface in the PixInsight core application.

The owner of the Real-Time Preview is the interface currently providing data for generation of real-time image renditions. Only one interface can own the Real-Time Preview at a given time.

Calling this function causes the immediate regeneration of the real-time image rendition, in the terms described for the Update() member function.

◆ SetProgressCount()

static void pcl::RealTimePreview::SetProgressCount ( size_type  count)
static

Sets the current value of the modal progress dialog associated with the Real-Time Preview interface to the specified count.

If the progress dialog is bounded, i.e. if you specified a nonzero total count when you called ShowProgressDialog(), then the count value set by this function should never be greater than the dialog's total count. If the dialog is unbounded, then you just have to increment the count to animate the dialog's busy state.

If a progress dialog is not visible after a successful call to ShowProgressDialog(), this function is simply ignored.

Referenced by pcl::RealTimeProgressStatus::Updated().

◆ SetProgressText()

static void pcl::RealTimePreview::SetProgressText ( const String &  text)
static

Sets the current single-line label's text shown on the modal progress dialog associated with the Real-Time Preview interface.

If a progress dialog is not visible after a successful call to ShowProgressDialog(), this function is simply ignored.

Referenced by pcl::RealTimeProgressStatus::InfoUpdated().

◆ ShowProgressDialog()

static void pcl::RealTimePreview::ShowProgressDialog ( const String &  title,
const String &  text,
size_type  total 
)
static

Requests a modal progress dialog associated with the Real-Time Preview interface during a real-time preview generation process.

Parameters
titleThe title of the modal progress dialog.
textThe informative text shown on the progress dialog. Keep in mind that this string will be shown on a single text line, so a reasonable maximum length should be about 50-60 characters.
totalTotal number of progress steps. The progress bar on the dialog can be incremented by successive calls to SetProgressCount() up to this value. If this parameter is zero, the progress dialog will be unbounded and will only show a busy state (typically, a progress bar bouncing horizontally at regular intervals).

This function allows you to show a modal dialog with a horizontal progress bar, a single-line text label and a standard Cancel button during long real-time generation procedures. These dialogs are useful to provide feedback to the user and to allow her or him to abort the ongoing real-time rendition task.

This member function can only be called during a real-time preview generation process, that is, when a reimplemented ProcessInterface::GenerateRealTimePreview() function is running. Calling this function when no real-time rendition is taking place has no effect.

Unlike most PCL routines involving dynamic changes to graphical interface elements, this function is thread-safe. You can safely call it from a running thread, which is a typical use because real-time generation tasks are normally (and should normally be) implemented as parallel threads to keep the GUI responsive. However, for the progress dialog to work it is necessary that the application's main event queue be active with sufficient granularity. In general, if you follow good UI programming techniques and use PCL example modules as a starting point to write your code, there should be no practical problems.

Note
Be aware that the progress dialog shown by this function is application-modal. This means that the only user interaction allowed while the dialog is visible is closing it, either by clicking its Cancel button, by pressing the Esc key, or by clicking its Close title bar icon. An important consequence of this is that you must ensure that your real-time generation process will end immediately and unconditionally when the dialog is closed. If your code is coherent with the GUI states of your process interface, the default PCL implementation should work. In some complex scenarios you may need to reimplement the ProcessInterface::CancelRealTimePreview() member function.

Referenced by pcl::RealTimeProgressStatus::Initialized().

◆ Update()

static void pcl::RealTimePreview::Update ( )
static

Generates a new Real-Time Preview image rendition.

A new real-time preview image can always be generated if there is a view currently selected on the Real-Time Preview window, if the selected view is not read-locked, and if the Real-Time Preview is not already busy. When all of that conditions are met, calling this function causes the immediate regeneration of the real-time preview image.

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