From 0f9c3a16952f077e2cd32193d6ce940e0af45cbf Mon Sep 17 00:00:00 2001 From: san Date: Wed, 10 Dec 2008 16:17:12 +0000 Subject: [PATCH] PARAVIS HTML docs --- doc/salome/gui/doxyfile.in | 2 +- src/PVGUI/PVGUI_Module.cxx | 153 ++++++++++++++++++++---- src/PVGUI/PVGUI_Module.h | 28 ----- src/PVGUI/PVGUI_ProcessModuleHelper.cxx | 28 +++++ src/PVGUI/PVGUI_ProcessModuleHelper.h | 20 +--- 5 files changed, 162 insertions(+), 69 deletions(-) diff --git a/doc/salome/gui/doxyfile.in b/doc/salome/gui/doxyfile.in index 1ad067ac..a60c13ef 100755 --- a/doc/salome/gui/doxyfile.in +++ b/doc/salome/gui/doxyfile.in @@ -3,7 +3,7 @@ #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -PROJECT_NAME = "ParaViS Module Programming Guide v.@VERSION@" +PROJECT_NAME = "ParaViS Module v.@VERSION@" PROJECT_NUMBER = OUTPUT_DIRECTORY = PARAVIS CREATE_SUBDIRS = NO diff --git a/src/PVGUI/PVGUI_Module.cxx b/src/PVGUI/PVGUI_Module.cxx index 9551b0b7..cb5fe5be 100644 --- a/src/PVGUI/PVGUI_Module.cxx +++ b/src/PVGUI/PVGUI_Module.cxx @@ -140,6 +140,136 @@ vtkPVMain* PVGUI_Module::pqImplementation::myPVMain = 0; pqOptions* PVGUI_Module::pqImplementation::myPVOptions = 0; PVGUI_ProcessModuleHelper* PVGUI_Module::pqImplementation::myPVHelper = 0; +/*! + \mainpage + +

Building and installing PARAVIS

+ As any other SALOME module, PARAVIS requires PARAVIS_ROOT_DIR environment variable to be set to PARAVIS + installation directory. + Other variables needed for correct detection of ParaView location: + \li PVSRCHOME - points at the root of ParaView source directory tree + \li PVINSTALLHOME - points at the top of ParaView build tree (currently, due to some drawbacks in its buld procedure + ParaView should not be installed, its build directory is used instead). + + It also requires common SALOME environment including GUI_ROOT_DIR and other prerequsites. + + As soon as the environment is set, excute the following commands in a shell: + \code + mkdir PARAVIS_BUILD + cd PARAVIS_BUILD + ../PARAVIS_SRC/build_configure + ../PARAVIS_SRC/configure --prefix=${PARAVIS_ROOT_DIR} + make + make docs + make install + \endcode + + PARAVIS module can be launched using the following commands: + \li Light SALOME configuration + \code + runLightSalome.sh --modules="PARAVIS" + \endcode + or + \li Full SALOME configuration + \code + runSalome --modules="PARAVIS" + \endcode + +

ParaView GUI integration

+

ParaView GUI integration overview

+ + The main idea is to reuse ParaView GUI internal logic as much as possible, providing a layer + between it and SALOME GUI that hides the following SALOME GUI implementation details from ParaView: + + \li SALOME GUI executable and Qt event loop + \li SALOME GUI desktop + \li Dock windows areas + \li SALOME menu and toolbar managers + + Major part of the integration is implemented in PVGUI_Module class. + +

ParaView client initalization

+ + ParaView client initalization is performed when an instance of PVGUI_Module class has been created + and \link PVGUI_Module::initialize() PVGUI_Module::initialize()\endlink method is called by SALOME GUI. + The actual client start-up is done in \link PVGUI_Module::pvInit() PVGUI_Module::pvInit()\endlink method. + It simulates actions perfomed by pqMain::Run( QApplication&, pqProcessModuleGUIHelper* ) method. + + Custom PVGUI_ProcessModuleHelper class derived from %pqProcessModuleGUIHelper base is the main actor in ParaView + client initialization. It initializes the client that uses the main window (SALOME desktop) supplied from the outside, + it does not start Qt event loop as this is done in SALOME GUI executable (SUITApp or SALOME_Session_Server), and after all + it redirects ParaView diagnostic output to SALOME LogWindow with help of PVGUI_OutputWindowAdapter class. + This is achieved by reimplementing \link PVGUI_ProcessModuleHelper::InitializeApplication() InitializeApplication()\endlink, + \link PVGUI_ProcessModuleHelper::appExec() appExec()\endlink, \link PVGUI_ProcessModuleHelper::postAppExec() postAppExec()\endlink + virtual methods as well as those responsible for main window management. + +

ParaView GUI connection to SALOME desktop

+ + ParaView Qt components include pqMainWindowCore class that handles most ParaView GUI client actions, + updates menu states and connects many GUI components. + After the client initalization \link PVGUI_Module::initialize() PVGUI_Module::initialize()\endlink method creates + an instance of internal PVGUI_Module::pqImplementation class (declared PVGUI_Module_impl.h) that wraps some ParaView GUI components: + pqMainWindowCore, pqServer, etc. Instance of SALOME desktop widget is passed to pqMainWindowCore instead of ParaView main window. + + Basically it simulates constructor of ParaView client's %MainWindow class (src/Applications/Client/MainWindow.cxx). It creates the same + menu and toolbar commands using SALOME menu and toolbar managers, connecting the actions to %pqMainWindowCore slots or to the module's + slots in some cases. It also sets up dock widgets for ParaView widgets, such as object inspector, pipeline browser, etc. + + As both SALOME destop and ParaView main winodw classes inherit QMainWindow and %pqMainWindowCore deals with QMainWindow API to control + menus, tollbars and dock widgets, its integration into SALOME GUI is straightforward and smooth. + +

Multi-view manager

+ + SALOME GUI requires that each kind of view be implemnted with help of (at least) three classes. For ParaView multi-view manager + these are: + + \li PVGUI_ViewManager - view manager class + \li PVGUI_Viewer - view model class + \li PVGUI_ViewWindow - view window class that acts as a parent for %pqViewManager + + Single instances of PVGUI_ViewManager and PVGUI_ViewWindow classes are created by \link PVGUI_Module::showView() + PVGUI_Module::showView()\endlink method upon the first PARAVIS module activation. The same method hides the multi-view manager + when the module is deactivated (the user switches to another module or a study is closed). + A special trick is used to make PVGUI_ViewWindow the parent of %pqViewManager widget. It is created initally by %pqMainWindowCore + with the desktop as a parent, so when it is shown PVGUI_ViewWindow instance is passed to its setParent() method. In + \link PVGUI_ViewWindow::~PVGUI_ViewWindow() PVGUI_ViewWindow::~PVGUI_ViewWindow()\endlink the parent is nullified to avoid deletion + of %pqViewManager widget that would break %pqMainWindowCore class. + +

ParaView plugins

+ ParaView server and client plugins are managed by %pqMainWindowCore slots that has full access to PARAVIS menus and toolbars. + As a result they appears automatically in PARAVIS menus and toolbars if loaded successfully. + +

Limitations of 2008 year prototype

+ \li SALOME persistence (possibility to save the module data into a tsudy file) is not implemented for PARAVIS module. + \li As a light module, PARAVIS does not have a CORBA engine that follows SALOME rules, however PARAVIS can use load a CORBA engine + on its own if needed. +*/ + +/* + A link to the file documentation PVGUI_Module_actions.cxx + + A link to the file documentation PVGUI_Module_impl.h + + A link to the class documentation PVGUI_Module + + The class name as a text (not a link to its documentation) %PVGUI_Module + + A link to the constructor of the class PVGUI_ViewWindow#PVGUI_ViewWindow or PVGUI_Module::PVGUI_Module() + + A link to the destructor of the class PVGUI_ViewWindow#~PVGUI_ViewWindow + + A link to the member function PVGUI_ViewWindow::getVisualParameters or PVGUI_ViewWindow#getVisualParameters + + Arguments of a function should be specified only for the overloaded functions PVGUI_Module::initialize(CAM_Application*) + + A link to some enumeration values PVGUI_Module::OpenFileId and PVGUI_Module::CreateLookmarkId + + A link to a protected member variable of the class PVGUI_ViewWindow#myModel + + A link to a variable \link PVGUI_ViewWindow#myModel using another text\endlink as a link + +*/ + /*! \class PVGUI_Module \brief Implementation of light (no-CORBA-engine) @@ -167,7 +297,7 @@ PVGUI_Module::~PVGUI_Module() /*! \brief Initialize module. Creates menus, prepares context menu, etc. - \param app application instance + \param app SALOME GUI application instance */ void PVGUI_Module::initialize( CAM_Application* app ) { @@ -217,24 +347,6 @@ void PVGUI_Module::windows( QMap& m ) const m.insert( LightApp_Application::WT_LogWindow, Qt::BottomDockWidgetArea ); } -/*! - \brief Create custom popup menu selection object. - \return new selected object -*/ -/*LightApp_Selection* PVGUI_Module::createSelection() const -{ - return new PVGUI_Selection(); -}*/ - -/*! - \brief Create data model. - \return module specific data model -*/ -/*CAM_DataModel* PVGUI_Module::createDataModel() -{ - return new PVGUI_DataModel( this ); -}*/ - /*! \brief Static method, performs initialization of ParaView session. \return \c true if ParaView has been initialized successfully, otherwise false @@ -243,7 +355,6 @@ bool PVGUI_Module::pvInit() { if ( !pqImplementation::myPVMain ){ // Obtain command-line arguments - // Workaround to avoid pqOptions messages: pass only the executable path to vtkPVMain int argc = 0; QStringList args = QApplication::arguments(); char** argv = new char*[args.size()]; @@ -284,7 +395,7 @@ bool PVGUI_Module::pvInit() } /*! - \brief Static method, cleans up ParaView session at application exit. + \brief Static method, cleans up ParaView session at application exit. Not yet implemented. */ void PVGUI_Module::pvShutdown() { diff --git a/src/PVGUI/PVGUI_Module.h b/src/PVGUI/PVGUI_Module.h index ba573470..6918361e 100644 --- a/src/PVGUI/PVGUI_Module.h +++ b/src/PVGUI/PVGUI_Module.h @@ -23,34 +23,6 @@ // Author : Sergey ANIKIN // -/*! - \mainpage - - Insert the content of introduction page here. - - A link to the file documentation PVGUI_Module_actions.cxx - - A link to the file documentation PVGUI_Module_impl.h - - A link to the class documentation PVGUI_Module - - The class name as a text (not a link to its documentation) %PVGUI_Module - - A link to the constructor of the class PVGUI_ViewWindow#PVGUI_ViewWindow or PVGUI_Module::PVGUI_Module() - - A link to the destructor of the class PVGUI_ViewWindow#~PVGUI_ViewWindow - - A link to the member function PVGUI_ViewWindow::getVisualParameters or PVGUI_ViewWindow#getVisualParameters - - Arguments of a function should be specified only for the overloaded functions PVGUI_Module::initialize(CAM_Application*) - - A link to some enumeration values PVGUI_Module::OpenFileId and PVGUI_Module::CreateLookmarkId - - A link to a protected member variable of the class PVGUI_ViewWindow#myModel - - A link to a variable \link PVGUI_ViewWindow#myModel using another text\endlink as a link - -*/ #ifndef PVGUI_Module_H #define PVGUI_Module_H diff --git a/src/PVGUI/PVGUI_ProcessModuleHelper.cxx b/src/PVGUI/PVGUI_ProcessModuleHelper.cxx index 7079c52a..642c46ac 100644 --- a/src/PVGUI/PVGUI_ProcessModuleHelper.cxx +++ b/src/PVGUI/PVGUI_ProcessModuleHelper.cxx @@ -51,6 +51,9 @@ void PVGUI_ProcessModuleHelper::PrintSelf(ostream& os, vtkIndent indent) } //----------------------------------------------------------------------------- +/*! + \brief Used by ParaView testing capabilities, not usable in SALOME. + */ bool PVGUI_ProcessModuleHelper::compareView(const QString& ReferenceImage, double Threshold, ostream& Output, const QString& TempDirectory) { @@ -62,22 +65,35 @@ bool PVGUI_ProcessModuleHelper::compareView(const QString& ReferenceImage, } //----------------------------------------------------------------------------- +/*! + \brief Reimplemented to suppress default ParaView client behavior. Does nothing. +*/ void PVGUI_ProcessModuleHelper::showOutputWindow() { // Do nothing here } //----------------------------------------------------------------------------- +/*! + \brief Reimplemented to suppress default ParaView client behavior. Does nothing. +*/ void PVGUI_ProcessModuleHelper::showWindow() { } //----------------------------------------------------------------------------- +/*! + \brief Reimplemented to suppress default ParaView client behavior. Does nothing. +*/ void PVGUI_ProcessModuleHelper::hideWindow() { } //----------------------------------------------------------------------------- +/*! + \brief Calls the base implementation and redirects ParaView output to PVGUI_OutputWindowAdapter instance. + \sa PVGUI_OutputWindowAdapter +*/ int PVGUI_ProcessModuleHelper::InitializeApplication(int argc, char** argv) { if ( pqProcessModuleGUIHelper::InitializeApplication( argc, argv ) ){ @@ -89,17 +105,26 @@ int PVGUI_ProcessModuleHelper::InitializeApplication(int argc, char** argv) } //----------------------------------------------------------------------------- +/*! + \brief Reimplemented to suppress default ParaView client behavior and not to run Qt event loop. Does nothing. +*/ int PVGUI_ProcessModuleHelper::appExec() { return 0; } +/*! + \brief Reimplemented to suppress default ParaView client behavior and not to exit after the client initalization. Does nothing. +*/ //----------------------------------------------------------------------------- int PVGUI_ProcessModuleHelper::postAppExec() { return 0; } +/*! + \brief Reimplemented to suppress default ParaView client behavior. Does nothing. +*/ //----------------------------------------------------------------------------- QWidget* PVGUI_ProcessModuleHelper::CreateMainWindow() { @@ -107,6 +132,9 @@ QWidget* PVGUI_ProcessModuleHelper::CreateMainWindow() } //----------------------------------------------------------------------------- +/*! + \brief Reimplemented to suppress default ParaView client behavior. Does nothing. +*/ void PVGUI_ProcessModuleHelper::ExitApplication() { // Cannot exit here, so do nothing diff --git a/src/PVGUI/PVGUI_ProcessModuleHelper.h b/src/PVGUI/PVGUI_ProcessModuleHelper.h index 5550d096..87bc3aca 100644 --- a/src/PVGUI/PVGUI_ProcessModuleHelper.h +++ b/src/PVGUI/PVGUI_ProcessModuleHelper.h @@ -30,7 +30,7 @@ /*! \class PVGUI_ProcessModuleHelper - The key element of ParaView integration into SALOME GUI. + One of the key elements of ParaView integration into SALOME GUI. Sub-classes pqProcessModuleGUIHelper with the following main features: \li No main window is created by this class \li Qt event loop is run outside this class @@ -44,42 +44,24 @@ public: vtkTypeRevisionMacro(PVGUI_ProcessModuleHelper, pqProcessModuleGUIHelper); void PrintSelf(ostream& os, vtkIndent indent); - //! Compares the contents of the window with the given reference image, returns true iff they "match" within some tolerance virtual bool compareView(const QString& ReferenceImage, double Threshold, ostream& Output, const QString& TempDirectory); - //! Redefined to supress showing a default output window, as the messages are redirected - //! to SALOME GUI message console virtual void showOutputWindow(); - - //! Stub for main window virtual void showWindow(); - //! Stub for main window virtual void hideWindow(); protected: - //! Calls the base implementation and then creates a custom output window adaptor virtual int InitializeApplication(int argc, char** argv); - //! Redefined to prevent QApplication::exec() call virtual int appExec(); - - //! Redefined to do nothing at the end of RunGUIStart(). - //! FinalizeApplication() should be called when the SALOME module - //! is destroyed. virtual int postAppExec(); PVGUI_ProcessModuleHelper(); ~PVGUI_ProcessModuleHelper(); - //! Stub for main window, returns a null pointer virtual QWidget* CreateMainWindow(); - - //! Called by vtkProcessModule, but we cannot exit here. virtual void ExitApplication(); - //! Returns the number of errors registered in the OutputWindow - //virtual int ErrorCount(); - private: PVGUI_ProcessModuleHelper(const PVGUI_ProcessModuleHelper&); // Not implemented. void operator=(const PVGUI_ProcessModuleHelper&); // Not implemented. -- 2.39.2