From 1de02033861dd64cb5a6f723da8bee6a7b0ae56a Mon Sep 17 00:00:00 2001 From: sln Date: Wed, 13 Jul 2005 10:37:36 +0000 Subject: [PATCH] Doxygen comments --- src/SUIT/SUIT_Operation.cxx | 291 +++++++++++++++++------------ src/SUIT/SUIT_Operation.h | 226 +--------------------- src/SalomeApp/SalomeApp_Module.cxx | 75 ++++++-- src/SalomeApp/SalomeApp_Module.h | 6 +- 4 files changed, 238 insertions(+), 360 deletions(-) diff --git a/src/SUIT/SUIT_Operation.cxx b/src/SUIT/SUIT_Operation.cxx index 64e60cd9b..cfaf3d431 100755 --- a/src/SUIT/SUIT_Operation.cxx +++ b/src/SUIT/SUIT_Operation.cxx @@ -17,10 +17,15 @@ #include "SUIT_MessageBox.h" #include "SUIT_Desktop.h" -//======================================================================= -// name : SUIT_Operation -// Purpose : Constructor -//======================================================================= +/*! + * \brief Constructor + * \param SUIT_Application - application for this operation +* +* Constructs an empty operation. Constructor should work very fast because many +* operators may be created after starting application but only several from them +* may be used. As result this constructor stores given application in myApp field +* and set Waiting status. +*/ SUIT_Operation::SUIT_Operation( SUIT_Application* app ) : QObject(), myApp( app ), @@ -29,70 +34,88 @@ myState( Waiting ) { } +/*! + * \brief Destructor +*/ SUIT_Operation::~SUIT_Operation() { } -//======================================================================= -// name : study -// Purpose : Gets operation study (i.e. study which starts this operation ) -//======================================================================= +/*! + * \brief Returns operation study + * \return Pointer to study +* +* Get study corresponding to this operation i.e. study which starts this operation. +*/ SUIT_Study* SUIT_Operation::study() const { return myStudy; } -//======================================================================= -// name : setStudy -// Purpose : Sets operation study (i.e. study which starts this operation ) -//======================================================================= +/*! + * \brief Sets operation study + * \param theStudy - study corresponding to this operation +* +* Sets study corresponding to this operation i.e. study which starts this operation. +*/ void SUIT_Operation::setStudy( SUIT_Study* theStudy ) { myStudy = theStudy; } -//======================================================================= -// name : application -// Purpose : Returns application -//======================================================================= +/*! + * \brief Gets application + * \return Pointer to application +* +* Gets application for this operation +*/ SUIT_Application* SUIT_Operation::application() const { return myApp; } -//======================================================================= -// name : setApplication -// Purpose : Sets application -//======================================================================= +/*! + * \brief Sets application + * \param theApp - application for this operation +* +* Gets application for this operation +*/ void SUIT_Operation::setApplication( SUIT_Application* theApp ) { myApp = theApp; } -//======================================================================= -// name : state -// Purpose : Returns state of operation (see OperationState enumeration) -//======================================================================= +/*! + * \brief Gets state of operation + * \return Value from OperationState enumeration +* +* Gets state of operation (see OperationState enumeration) +*/ SUIT_Operation::OperationState SUIT_Operation::state() const { return myState; } -//======================================================================= -// name : setState -// Purpose : Sets state of operation (see OperationState enumeration) -//======================================================================= +/*! + * \brief Sets state of operation + * \param theState - state of operation to be set +* +* Sets state of operation (see OperationState enumeration) +*/ void SUIT_Operation::setState( const SUIT_Operation::OperationState theState ) { myState = theState; } -//======================================================================= -// name : start -// Purpose : Verifies whether operation can be started and starts operation. This slot -// is not virtual and cannot be redefined. Redefine startOperation method -// to change behaviour of operation instead -//======================================================================= +/*! + * \brief Starts operation +* +* Public slot. Verifies whether operation can be started and starts operation. +* This slot is not virtual and cannot be redefined. Redefine startOperation method +* to change behavior of operation. There is no point in using this method. It would +* be better to inherit own operator from base one and redefine startOperation method +* instead. +*/ void SUIT_Operation::start() { if ( study() ) @@ -104,12 +127,12 @@ void SUIT_Operation::start() } } -//======================================================================= -// name : abort -// Purpose : Aborts operation. This slot is not virtual and cannot be -// redefined. Redefine abortOperation method to change behaviour -// of operation instead -//======================================================================= +/*! + * \brief Aborts operation +* +* Public slot. Aborts operation. This slot is not virtual and cannot be redefined. +* Redefine abortOperation method to change behavior of operation instead +*/ void SUIT_Operation::abort() { if ( study() ) @@ -123,12 +146,12 @@ void SUIT_Operation::abort() } } -//======================================================================= -// name : commit -// Purpose : Commits operation. This slot is not virtual and cannot be -// redefined. Redefine commitOperation method to change behaviour -// of operation instead -//======================================================================= +/*! + * \brief Commits operation +* +* Public slot. Commits operation. This slot is not virtual and cannot be redefined. +* Redefine commitOperation method to change behavior of operation instead +*/ void SUIT_Operation::commit() { if ( study() ) @@ -142,13 +165,13 @@ void SUIT_Operation::commit() } } -//======================================================================= -// name : resume -// Purpose : Resume operation. This slot is called when operation is -// resumed after previous suspending. This slot is not virtual -// and cannot be redefined. Redefine resumeOperation method -// to change behaviour of operation instead -//======================================================================= +/*! + * \brief Resumes operation +* +* Public slot. Resumes operation. This slot is called when operation is resumed after +* previous suspending. This slot is not virtual and cannot be redefined. Redefine +* resumeOperation method to change behavior of operation instead +*/ void SUIT_Operation::resume() { if ( study() ) @@ -161,13 +184,13 @@ void SUIT_Operation::resume() } } -//======================================================================= -// name : suspend -// Purpose : Suspend operation. This slot is called when operation is -// suspended (for starting other one, for example). This slot is not -// virtual and cannot be redefined. Redefine suspendOperation -// method to change behaviour of operation instead -//======================================================================= +/*! + * \brief Suspend operation. +* +* Public slot. Suspend operation. This slot is called when operation is suspended +* (for starting other one, for example) This slot is not virtual and cannot be +* redefined. Redefine suspendOperation method to change behavior of operation instead +*/ void SUIT_Operation::suspend() { if ( study() ) @@ -180,109 +203,125 @@ void SUIT_Operation::suspend() } } -//======================================================================= -// name : isReadyToStart -// Purpose : Verify whether operator is ready to start. Default implementation -// returns true. Redefine this method to add own verifications -//======================================================================= +/*! + * \brief Verifies whether operator is ready to start. + * \return TRUE if operation is ready to start +* +* Default implementation returns TRUE. Redefine this method to add own verifications +*/ bool SUIT_Operation::isReadyToStart() const { return true; } -//======================================================================= -// name : startOperation -// Purpose : Virtual method called when operation started (see start() -// method for more description) -//======================================================================= +/*! + * \brief Virtual method called when operation is started +* +* Virtual method called when operation started (see start() method for more description) +*/ void SUIT_Operation::startOperation() { emit callSlot(); commit(); } -//======================================================================= -// name : abortOperation -// Purpose : Virtual method called when operation aborted (see abort() -// method for more description) -//======================================================================= +/*! + * \brief Virtual method called when operation aborted +* +* Virtual method called when operation aborted (see abort() method for more description) +*/ void SUIT_Operation::abortOperation() { } -//======================================================================= -// name : resumeOperation -// Purpose : Virtual method called when operation resumed (see resume() -// method for more description) -//======================================================================= +/*! + * \brief Virtual method called when operation resumed +* +* Virtual method called when operation resumed (see resume() method for more description) +*/ void SUIT_Operation::resumeOperation() { } -//======================================================================= -// name : suspendOperation -// Purpose : Virtual method called when operation suspended (see suspend() -// method for more description) -//======================================================================= +/*! + * \brief Virtual method called when operation suspended +* +* Virtual method called when operation suspended (see suspend() method for more description) +*/ void SUIT_Operation::suspendOperation() { } -//======================================================================= -// name : commitOperation -// Purpose : Virtual method called when operation committed (see commit() -// method for more description) -//======================================================================= +/*! + * \brief Virtual method called when operation committed +* +* Virtual method called when operation committed (see commit() method for more description) +*/ void SUIT_Operation::commitOperation() { } -//======================================================================= -// name : setSlot -// Purpose : Sets slot which is called when operation is started. There is no point in -// using this method. It would be better to inherit own operator from base -// one and redefine startOperation method. -//======================================================================= +/*! + * \brief Sets slot which is called when operation is started + * \param theReceiver - object containing slot + * \param theSlot - slot of theReceiver object + * \return TR if slot was connected successfully, FALSE otherwise +* +* Sets slot which is called when operation is started. There is no point in +* using this method. It would be better to inherit own operator from base +* one and redefine startOperation method +*/ bool SUIT_Operation::setSlot( const QObject* theReceiver, const char* theSlot ) { return connect( this, SIGNAL( callSlot() ), theReceiver, theSlot ); } -//======================================================================= -// name : isValid -// Purpose : Returns TRUE if the given operator is valid for the current one -// (can be started "above") -//======================================================================= +/*! + * \brief Verifies whether given operator is valid for this one + * \param theOtherOp - other operation + * \return Returns TRUE if the given operator is valid for this one +* +* Verifies whether given operator is valid for this one (i.e. can be started "above" +* this operator) +*/ bool SUIT_Operation::isValid( SUIT_Operation* ) const { return false; } -//======================================================================= -// name : isGranted -// Purpose : Returns TRUE if current operation must not be checked for -// ActiveOperation->IsValid(this). Default implementation returns FALSE, -// so it is being checked for IsValid, but some operations may overload IsGranted() -// In this case they will always start, no matter what operation is running -//======================================================================= +/*! + * \brief Verifies whether this operator can be always started above any already runnig one + * \return Returns TRUE if current operation must not be checked for ActiveOperation->IsValid( this ) +* +* This method must be redefined in derived operation if operation of derived class +* must be always can start above any launched one. Default implementation returns FALSE, +* so it is being checked for IsValid, but some operations may overload IsGranted() +* In this case they will always start, no matter what operation is running. +*/ bool SUIT_Operation::isGranted() const { return false; } -//======================================================================= -// name : isActive -// Purpose : Verify whether operation is an active one -//======================================================================= +/*! + * \brief Verifies whether operation is an active one (state()==Running) + * \return TRUE if operation is active, FALSE otherwise +* +* Verifies whether operation is an active on. Returns TRUE if state of operator +* is Running +*/ bool SUIT_Operation::isActive() const { return state()==Running; } -//======================================================================= -// name : start -// Purpose : Start operator above this one -//======================================================================= +/*! + * \brief Starts operator above this one + * \param theOp - operation to be started +* +* Start operator above this one. Use this method if you want to call other operator +* from this one +*/ void SUIT_Operation::start( SUIT_Operation* op ) { if ( !op ) @@ -297,19 +336,23 @@ void SUIT_Operation::start( SUIT_Operation* op ) } } -//======================================================================= -// name : setExecStatus -// Purpose : Sets myExecStatus to the given value -//======================================================================= +/*! + * \brief Sets execution status + * \param theStatus - execution status +* +* Sets myExecStatus to the given value +*/ void SUIT_Operation::setExecStatus( const int theVal ) { myExecStatus = (ExecStatus)theVal; } -//======================================================================= -// name : execStatus -// Purpose : Gets execution status -//======================================================================= +/*! + * \brief Gets execution status + * \return Execution status +* +* Gets execution status +*/ int SUIT_Operation::execStatus() const { return myExecStatus; diff --git a/src/SUIT/SUIT_Operation.h b/src/SUIT/SUIT_Operation.h index f3b3c73fb..7af280e8c 100755 --- a/src/SUIT/SUIT_Operation.h +++ b/src/SUIT/SUIT_Operation.h @@ -63,267 +63,57 @@ public: public: - /*! - * \brief Constructor - * \param SUIT_Application - application for this operation - * - * Constructs an empty operation. Constructor should work very fast because many - * operators may be created after starting application but only several from them - * may be used. As result this constructor stores given application in myApp field - * and set Waiting status. - */ SUIT_Operation( SUIT_Application* ); - - /*! - * \brief Destructor - */ virtual ~SUIT_Operation(); - /*! - * \brief Verifies whether operation is an active one (state()==Running) - * \return TRUE if operation is active, FALSE otherwise - * - * Verifies whether operation is an active on. Returns TRUE if state of operator - * is Running - */ - bool isActive() const; - - /*! - * \brief Gets state of operation - * \return Value from OperationState enumeration - * - * Gets state of operation (see OperationState enumeration) - */ OperationState state() const; + bool isActive() const; - /*! - * \brief Sets state of operation - * \param theState - state of operation to be set - * - * Sets state of operation (see OperationState enumeration) - */ - void setState( const OperationState theState ); - - /*! - * \brief Returns operation study - * \return Pointer to study - * Get study corresponding to this operation i.e. study which starts this operation. - */ SUIT_Study* study() const; - - /*! - * \brief Sets operation study - * \param theStudy - study corresponding to this operation - * - * Sets study corresponding to this operation i.e. study which starts this operation. - */ virtual void setStudy( SUIT_Study* theStudy ); - //!< Sets operation study (i.e. study which starts this operation ) - - /*! - * \brief Gets application - * \return Pointer to application - * - * Gets application for this operation - */ + SUIT_Application* application() const; - - /*! - * \brief Sets application - * \param theApp - application for this operation - * - * Gets application for this operation - */ virtual void setApplication( SUIT_Application* theApp ); - /*! - * \brief Sets slot which is called when operation is started - * \param theReceiver - object containing slot - * \param theSlot - slot of theReceiver object - * \return TR if slot was connected successfully, FALSE otherwise - * - * Sets slot which is called when operation is started. There is no point in - * using this method. It would be better to inherit own operator from base - * one and redefine startOperation method - */ - bool setSlot( const QObject* theReceiver, const char* theSlot ); - - /*! - * \brief Verifies whether given operator is valid for this one - * \param theOtherOp - other operation - * \return Returns TRUE if the given operator is valid for this one - * - * Verifies whether given operator is valid for this one (i.e. can be started "above" - * this operator) - */ virtual bool isValid( SUIT_Operation* theOtherOp ) const; - - /*! - * \brief Verifies whether this operator can be always started above any already runnig one - * \return Returns TRUE if current operation must not be checked for ActiveOperation->IsValid( this ) - * - * This method must be redefined in derived operation if operation of derived class - * must be always can start above any launched one. Default implementation returns FALSE, - * so it is being checked for IsValid, but some operations may overload IsGranted() - * In this case they will always start, no matter what operation is running. - */ virtual bool isGranted() const; + bool setSlot( const QObject* theReceiver, const char* theSlot ); + public slots: - /*! - * \brief Starts operation - * - * Public slot. Verifies whether operation can be started and starts operation. - * This slot is not virtual and cannot be redefined. Redefine startOperation method - * to change behavior of operation. There is no point in using this method. It would - * be better to inherit own operator from base one and redefine startOperation method - * instead. - */ void start(); - - /*! - * \brief Aborts operation - * - * Public slot. Aborts operation. This slot is not virtual and cannot be redefined. - * Redefine abortOperation method to change behavior of operation instead - */ void abort(); - - /*! - * \brief Commits operation - * - * Public slot. Commits operation. This slot is not virtual and cannot be redefined. - * Redefine commitOperation method to change behavior of operation instead - */ void commit(); - - /*! - * \brief Suspend operation. - * - * Public slot. Suspend operation. This slot is called when operation is suspended - * (for starting other one, for example) This slot is not virtual and cannot be - * redefined. Redefine suspendOperation method to change behavior of operation instead - */ void suspend(); - - /*! - * \brief Resumes operation - * - * Public slot. Resumes operation. This slot is called when operation is resumed after - * previous suspending. This slot is not virtual and cannot be redefined. Redefine - * resumeOperation method to change behavior of operation instead - */ void resume(); signals: - /*! - * \brief Signal emitted from start method when operation started - */ void started( SUIT_Operation* ); - - /*! - * \brief Signal emitted from start method when operation aborted - */ void aborted( SUIT_Operation* ); - - /*! - * \brief Signal emitted from start method when operation resumed - */ void resumed( SUIT_Operation* ); - - /*! - * \brief Signal emitted from committed method when operation committed - */ void committed( SUIT_Operation* ); - - /*! - * \brief Signal emited from suspend method when operation suspended - */ void suspended( SUIT_Operation* ); - - /*! - * \brief Signal emited from stop method when operation stopped - */ void stopped( SUIT_Operation* ); - - /*! - * \brief Signal emited from default implementation of startOperation method - * - * See setSlot for more description - */ + void callSlot(); protected: - /*! - * \brief Verifies whether operator is ready to start. - * \return TRUE if operation is ready to start - * - * Default implementation returns TRUE. Redefine this method to add own verifications - */ virtual bool isReadyToStart() const; - - /*! - * \brief Virtual method called when operation is started - * - * Virtual method called when operation started (see start() method for more description) - */ + virtual void startOperation(); - - /*! - * \brief Virtual method called when operation aborted - * - * Virtual method called when operation aborted (see abort() method for more description) - */ virtual void abortOperation(); - - /*! - * \brief Virtual method called when operation committed - * - * Virtual method called when operation committed (see commit() method for more description) - */ virtual void commitOperation(); - - /*! - * \brief Virtual method called when operation suspended - * - * Virtual method called when operation suspended (see suspend() method for more description) - */ - virtual void suspendOperation(); - - /*! - * \brief Virtual method called when operation resumed - * - * Virtual method called when operation resumed (see resume() method for more description) - */ virtual void resumeOperation(); - /*! - * \brief Sets execution status - * \param theStatus - execution status - * - * Sets myExecStatus to the given value - */ void setExecStatus( const int theStatus ); - - /*! - * \brief Gets execution status - * \return Execution status - * - * Gets execution status - */ int execStatus() const; - /*! - * \brief Starts operator above this one - * \param theOp - operation to be started - * - * Start operator above this one. Use this method if you want to call other operator - * from this one - */ + void setState( const OperationState theState ); + void start( SUIT_Operation* theOp ); private: diff --git a/src/SalomeApp/SalomeApp_Module.cxx b/src/SalomeApp/SalomeApp_Module.cxx index f3a8e6f1f..8b8b8ec6d 100644 --- a/src/SalomeApp/SalomeApp_Module.cxx +++ b/src/SalomeApp/SalomeApp_Module.cxx @@ -55,12 +55,18 @@ bool SalomeApp_Module::activateModule( SUIT_Study* study ) if ( res && application() && application()->resourceMgr() ) application()->resourceMgr()->raiseTranslators( name() ); + + if ( mySwitchOp == 0 ) + mySwitchOp = new SalomeApp_SwitchOp( this ); return res; } bool SalomeApp_Module::deactivateModule( SUIT_Study* ) { + delete mySwitchOp; + mySwitchOp = 0; + return true; } @@ -156,7 +162,8 @@ int SalomeApp_Module::addPreference( const QString& label ) int catId = pref->addPreference( moduleName(), -1 ); if ( catId == -1 ) return -1; - + * Updates (i.e. disable/enable) controls states (menus, tool bars etc.). This method is +* called from update( UF_Controls ). You may redefine it in concrete module. return pref->addPreference( label, catId ); } @@ -186,19 +193,27 @@ void SalomeApp_Module::setPreferenceProperty( const int id, const QString& prop, pref->setProperty( id, prop, var ); } -void SalomeApp_Module::update( const int flags ) +/*! + * \brief Update something in accordance with update flags + * \param theFlags - update flags +* +* Update viewer or/and object browser etc. in accordance with update flags ( see +* SalomeApp_UpdateFlags enumeration ). Derived modules can redefine this method for their +* own purposes +*/ +void SalomeApp_Module::update( const int theFlags ) { - if ( flags & UF_Model ) + if ( theFlags & UF_Model ) { if( CAM_DataModel* aDataModel = dataModel() ) if( SalomeApp_DataModel* aModel = dynamic_cast( aDataModel ) ) aModel->update( 0, dynamic_cast( getApp()->activeStudy() ) ); } - else if ( flags & UF_ObjBrowser ) + else if ( theFlags & UF_ObjBrowser ) getApp()->objectBrowser()->updateTree( 0 ); - else if ( flags & UF_Controls ) + else if ( theFlags & UF_Controls ) updateControls(); - else if ( flags & UF_Viewer ) + else if ( theFlags & UF_Viewer ) { if ( SUIT_ViewManager* viewMgr = getApp()->activeViewManager() ) if ( SUIT_ViewWindow* viewWnd = viewMgr->getActiveView() ) @@ -216,10 +231,24 @@ void SalomeApp_Module::update( const int flags ) } +/*! + * \brief Updates controls +* +* Updates (i.e. disable/enable) controls states (menus, tool bars etc.). This method is +* called from update( UF_Controls ). You may redefine it in concrete module. +*/ void SalomeApp_Module::updateControls() { } +/*! + * \brief Starts operation with given identifier + * \param id - identifier of operation to be started +* +* Module stores operations in map. This method starts operation by id. +* If operation isn't in map, then it will be created by createOperation method +* and will be inserted to map +*/ void SalomeApp_Module::startOperation( const int id ) { SalomeApp_Operation* op = 0; @@ -234,12 +263,6 @@ void SalomeApp_Module::startOperation( const int id ) op->setModule( this ); connect( op, SIGNAL( stopped( SUIT_Operation* ) ), this, SLOT( onOperationStopped( SUIT_Operation* ) ) ); connect( op, SIGNAL( destroyed() ), this, SLOT( onOperationDestroyed() ) ); - if ( mySwitchOp == 0 ) - { - mySwitchOp = new SalomeApp_SwitchOp( this ); - printf( "sln: new SalomeApp_SwitchOp\n" ); - } - mySwitchOp->connect( op ); } } @@ -247,15 +270,39 @@ void SalomeApp_Module::startOperation( const int id ) op->start(); } -SalomeApp_Operation* SalomeApp_Module::createOperation( const int ) const +/*! + * \brief Creates operation with given identifier + * \param id - identifier of operation to be started + * \return Pointer on created operation or NULL if operation is not created +* +* Creates operation with given id. You should not call this method, it will be called +* automatically from startOperation. You may redefine this method in concrete module to +* create operations. +*/ +SalomeApp_Operation* SalomeApp_Module::createOperation( const int /*id*/ ) const { return 0; } -void SalomeApp_Module::onOperationStopped( SUIT_Operation* ) +/*! + * \brief Virtual protected slot called when operation stopped + * \param theOp - stopped operation +* +* Virtual protected slot called when operation stopped. Redefine this slot if you want to +* perform actions after stopping operation +*/ +void SalomeApp_Module::onOperationStopped( SUIT_Operation* /*theOp*/ ) { } +/*! + * \brief Virtual protected slot called when operation destroyed + * \param theOp - destroyed operation +* +* Virtual protected slot called when operation destroyed. Redefine this slot if you want to +* perform actions after destroying operation. Base implementation removes pointer on +* destroyed operation from the map of operations +*/ void SalomeApp_Module::onOperationDestroyed() { const QObject* s = sender(); diff --git a/src/SalomeApp/SalomeApp_Module.h b/src/SalomeApp/SalomeApp_Module.h index d174902ac..780842d16 100644 --- a/src/SalomeApp/SalomeApp_Module.h +++ b/src/SalomeApp/SalomeApp_Module.h @@ -31,11 +31,9 @@ class SalomeApp_SelectionManager; class SalomeApp_Operation; class SalomeApp_SwitchOp; -/* - Class : SalomeApp_Module - Description : Base class for all salome modules +/*! + * \brief Base class for all salome modules */ - class SALOMEAPP_EXPORT SalomeApp_Module : public CAM_Module { Q_OBJECT -- 2.39.2