Filter Library

Camera

Interface Physics

ProgressDlg.h

/*
 * ProgressDlg.h - progress dialog for computational intensive operations.
 *
 * This file is part of the Camera Filter Library.
 * Computer Aided Measurement Environment for Realtime Atomic imaging (Camera)
 *
 * Copyright (C) 2005, Leiden Probe Microscopy.
 * Copyright (C) 2005, Universiteit Leiden.
 *
 * Author(s):
 *
 * $Id: ProgressDlg.h 347 2006-03-01 13:57:50Z moene $
 */

#ifndef CFL_PROGRESSDLG_H
#define CFL_PROGRESSDLG_H

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#include <afxmt.h>                      // for class CCriticalSection

/**
 * \addtogroup cfl_dialog
 *
 * @{
 */

/**
 * dialog to indicate progress of computational intensive operations, like
 * \ref cfl_filtercrosscorrelate "cross-correlation" in the spatial domain.
 *
 * The progress dialog is used to indicate the progress of computational intensive
 * operations and to enable the user to stop the computation prematurely.
 * See for example \ref cfl_filtercrosscorrelate "cross-correlation" in the 
 * spatial domain.
 *
 * Class CProgressDlg is used as follows.
 * - the filter class creates a CProgressDlg object and saves information about itself in it;
 *   the progress dialog sets-up a timer to update its progress bar
 * - the filter class creates a suspended worker thread to do the computation
 * - the filter class calls dlg.DoModal( hThread ) wich resumes the worker thread
 * - the worker thread sets the progress bar range and text variables
 * - the worker thread performs the computation and based on its progress, updates
 *   the dialog's progress bar position variable
 * - the timer lets the progress dialog periodically update its text and progress 
 *   bar range and position
 * - finally the worker thread terminates the progress dialog by sending it a
 *   WM_CLOSE message (see CProgressDlg::Terminate() )
 * - WM_CLOSE activates the dialog's OnCancel() handler which stops the timer
 *   used to update the progress bar
 *
 * The user may cancel the computation prematurely by pressing the Cancel-button
 * on the progress dialog or by pressing the Esc-key.
 * In this case the progress dialog's OnCancel() handler is called and the
 * following happens.
 * - OnCancel() sets a flag to signal the computation to stop (dlg->StopRequested())
 * - OnCancel() waits for the worker thread to finish, unless it has not been
 *   resumed before
 * - OnCancel() stops the timer used to update the dialog's progress bar
 * - the worker thread calls CProgressDlg::Terminate() but in the case it may not
 *   and does not generate a WM_CLOSE message, because the dialog is closing
 *   already ( CProgressDlg::IsCanceling() )
 *
 * <b>Note 1</b>: handling of the Esc-key press was not implemented in the original version.\n
 * <b>Note 2</b>: waiting for the worker thread was not implemented in the original version.
 *
 * Class CProgressDlg uses a critical section (CCriticalSection) to guard access
 * to the dialog text, and progress bar range and position from different threads.
 *
 * For more information, see the implementation of class CScanFilterCrossCorrelate.
 */
class CProgressDlg : public CDialog
{
public:
   ///
   /// \name Construction
   /// @{

   /**
    * (default) constructor.
    */
   CProgressDlg( CWnd* pParent = NULL );

   /**
    * destructor.
    */
   ~CProgressDlg();

   /// @}
   /// \name Predicates
   /// @{

   /**
    * the thread has informed us that it has been resumed.
    */
   BOOL IsResumed();

   /**
    * Cancel-button or Escape-key pressed (window close message).
    */
   BOOL IsCanceling();

   /**
    * Cancel-button or Esc-key pressed; alias for IsCanceling().
    */
   BOOL StopRequested();

   /// @}
   /// \name Mutators
   /// @{

   /**
    * set resumed flag.
    */
   void SetResumed();

   /**
    * set progress bar range; Note just store, OnTimer updates dialog.
    */
   void SetRange( int nLower, int nUpper );

   /**
    * set progress bar position; Note just store, OnTimer updates dialog.
    */
   void SetPos( int nPos );

   /**
    * set progress dialog message text; Note just store, OnTimer updates dialog.
    */
   void SetText( LPCTSTR lpcsText );

   /**
    * close the progress dialog window.
    */
   void Terminate();

   /**
    * display dialog as a modal window.
    */
   virtual int DoModal( CWinThread *pTread = NULL );

   /// @}

protected:
   /**
    * Dialog Data Exchange (DDX) / Dialog Data Validation (DDV) support.
    */
   // ClassWizard generated virtual function overrides
   //{{AFX_VIRTUAL(CProgressDlg)
   virtual void DoDataExchange(CDataExchange* pDX);    // DDX/DDV support
   //}}AFX_VIRTUAL

   // Generated message map functions
   //{{AFX_MSG(CProgressDlg)
   virtual BOOL OnInitDialog();         ///< initialize the dialog
   afx_msg void OnCancel();             ///< handle cancel message (button)
   afx_msg void OnClose();              ///< handle close message (button, Esc)
   afx_msg void OnTimer( UINT nIDEvent ); ///< handle timer event
   //}}AFX_MSG
   DECLARE_MESSAGE_MAP()

   /**
    * resume the given thread.
    */
   BOOL ResumeComputationThread( CWinThread *pThread );

protected:
   CWinThread*      m_pThread;          ///< the computation thread
   SECProgressCtrl  m_wndProgress;      ///< advanced progress bar from Rogue Wave Objective Toolkit
   volatile BOOL    m_bInitialized;     ///< dialog is initialized flag
   volatile BOOL    m_bCancel;          ///< Cancel-button or Esc-key pressed flag
   volatile BOOL    m_bResumed;         ///< computation thread has been resumed flag
   CString          m_csMessage;        ///< progress dialog message text
   volatile int     m_nLowerPosition;   ///< progress bar lower position
   volatile int     m_nUpperPosition;   ///< progress bar upper position
   volatile int     m_nCurrentPosition; ///< progress bar current position

private:
   //{{AFX_DATA(CProgressDlg)
   enum { IDD = IDD_PROGRESSDLG };
        //}}AFX_DATA

   /**
    * our timer event.
    */
   static const int c_nTimerIDEvent;

   /**
    * critical section guard.
    */
   CCriticalSection m_criticalSection;
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Visual C++ will insert additional declarations immediately before the previous line.

/// @}

#endif // #ifndef CFL_PROGRESSDLG_H

/*
 * end of file
 */

---