From dfdb2899a4cb4eaea4cdce45fa7c05ec0c5c807a Mon Sep 17 00:00:00 2001 From: vsv Date: Tue, 27 Jan 2015 20:05:45 +0300 Subject: [PATCH] Update code documentation --- doc/Modules.doc | 33 ++++++++++- src/ModuleBase/ModuleBase_Preferences.h | 20 ++++++- .../ModuleBase_WidgetMultiSelector.h | 2 +- src/ModuleBase/ModuleBase_WidgetSwitch.h | 56 +++++++++++++++++++ src/NewGeom/NewGeom_DataModel.h | 35 +++++++++++- src/XGUI/XGUI_ActionsMgr.h | 13 +++++ src/XGUI/XGUI_ObjectsBrowser.h | 33 ++++++++++- 7 files changed, 185 insertions(+), 7 deletions(-) diff --git a/doc/Modules.doc b/doc/Modules.doc index c507c4e5c..bd6433925 100644 --- a/doc/Modules.doc +++ b/doc/Modules.doc @@ -28,8 +28,39 @@ * * The C++ and Python features implementations are located in plugins: specially organized libraries * and configuration files that allows to define the user interface and specific algorithms. - * There are many plugins that should be extended wit hthe development of the application. The names + * There are many plugins that should be extended with the development of the application. The names * of plugin-packages are ended with "Plugin" string: * PartSetPlugin, ConstructionPlugin, SketchPlugin, FeaturesPlugins, etc. * */ + +/** + * \defgroup GUI GUI of the application + * + * \brief Classes for griphic user interface definition + * + * Classes of application windows definition, operations launching, + * and objects presentations. It consists of two packages: + * - ModuleBase - level for modules definition + * - XGUI - implementation of Application GUI. + */ + +/** + * \defgroup Salome A Salome connector + * + * \brief A set of classes which provide wrapping of + * OpenParts application as SALOME module + */ + +/** + * \defgroup Desktop Classes for standalone application + * + * \brief This group contains classes for launching the application + * in standalone desktop (without SALOME) + */ + +/** + * \defgroup Modules Modules + * + * \brief Definition of a module as a set of classes for plugins management + */ \ No newline at end of file diff --git a/src/ModuleBase/ModuleBase_Preferences.h b/src/ModuleBase/ModuleBase_Preferences.h index b7783c09d..d156f5f70 100644 --- a/src/ModuleBase/ModuleBase_Preferences.h +++ b/src/ModuleBase/ModuleBase_Preferences.h @@ -16,10 +16,10 @@ class SUIT_ResourceMgr; class QWidget; -/// \typedef ModuleBase_Pref Pair of values: section name, value name +/// Pair of values: section name, value name typedef QPair ModuleBase_Pref; -/// \typedef ModuleBase_Prefs list of preferences +/// List of preferences typedef QList ModuleBase_Prefs; //*********************************************************************** @@ -27,9 +27,14 @@ typedef QList ModuleBase_Prefs; class MODULEBASE_EXPORT ModuleBase_Preferences { public: + /// Name of preferences of viewer section static const QString VIEWER_SECTION; + + /// Name of preferences of menu section static const QString MENU_SECTION; + /// Shows a dialog box to edit preferences + /// \param theModified a list of modified preferences static bool editPreferences(ModuleBase_Prefs& theModified); /// Returns currently installed resource manager @@ -44,7 +49,6 @@ class MODULEBASE_EXPORT ModuleBase_Preferences static void updateConfigByResources(); /// Updates SUIT_ResourceMgr values by Config_PropManager properties - /// \param theUpdateOnlyInvalid flag to update only invalid values, if it is false, all are updated static void updateResourcesByConfig(); /// Set default values to the Config_PropManager properties @@ -83,12 +87,14 @@ Q_OBJECT { } + /// Returns True if preferences were modified ModuleBase_Prefs modified() const { return myModified; } protected: + /// Store changed resource virtual void changedResources(const ResourceMap& theMap); private: @@ -101,20 +107,28 @@ class MODULEBASE_EXPORT ModuleBase_PreferencesDlg : public QDialog { Q_OBJECT public: + /// Constructor + /// \param theResurces resources manager + /// \param theParent a parent widget ModuleBase_PreferencesDlg(SUIT_ResourceMgr* theResurces, QWidget* theParent = 0); virtual ~ModuleBase_PreferencesDlg(); + /// Returns True if preferences were changed bool isChanged() const { return myIsChanged; } + /// Returns list of modified preferences + /// \param theModified output list of modified preferences void modified(ModuleBase_Prefs& theModified) const; public slots: + /// A slot called on Ok button press virtual void accept(); protected slots: + /// A slot called on Default button press void onDefault(); private: diff --git a/src/ModuleBase/ModuleBase_WidgetMultiSelector.h b/src/ModuleBase/ModuleBase_WidgetMultiSelector.h index 66ef0bc87..b65b4812b 100644 --- a/src/ModuleBase/ModuleBase_WidgetMultiSelector.h +++ b/src/ModuleBase/ModuleBase_WidgetMultiSelector.h @@ -124,7 +124,7 @@ protected slots: /// If true then local selector has to be activated in context bool myIsActive; - /// \typedef GeomSelection provides correspondance between Result object and its shape + /// Provides correspondance between Result object and its shape typedef QPair GeomSelection; /// Variable of GeomSelection type diff --git a/src/ModuleBase/ModuleBase_WidgetSwitch.h b/src/ModuleBase/ModuleBase_WidgetSwitch.h index e6e6eec91..f105bc6fd 100644 --- a/src/ModuleBase/ModuleBase_WidgetSwitch.h +++ b/src/ModuleBase/ModuleBase_WidgetSwitch.h @@ -16,39 +16,95 @@ class QComboBox; class QVBoxLayout; +/** +* \ingroup GUI +* Implements a model widget for swithch as a container widget. It can be defined in XML with "switch" keyword +*/ class MODULEBASE_EXPORT ModuleBase_WidgetSwitch : public QFrame { Q_OBJECT public: + /// Constructor + /// \param parent a parent widget ModuleBase_WidgetSwitch(QWidget* parent = NULL); virtual ~ModuleBase_WidgetSwitch(); + /// Add a page to the widget + /// \param theWidget a page widget + /// \param theName a name of page int addPage(QWidget * theWidget, const QString & theName); + + /// Returns count of pages int count() const; + + /// Returns index of current page int currentIndex() const; + + /// Returns current widget (page) QWidget * currentWidget() const; + + /// Returns index of widget (page) + /// \param theWidget a widget page int indexOf(QWidget * theWidget) const; + + /// Insert page + /// \param index an index (position) to insert + /// \param theWidget a page widget + /// \param theName a name of the page int insertPage(int index, QWidget * theWidget, const QString & theName); + + /// Returns True if a page by given index is enabled + /// \param index index of the page bool isPageEnabled(int index) const; + + /// Returns text of the page by its id + /// \param index index of the page QString pageText(int index) const; + + /// Returns tooltip of the page by its id + /// \param index index of the page QString pageToolTip(int index) const; + + /// Remove page by its id + /// \param index index of the page void removePage(int index); + + /// Enale/disable a page by its Id + /// \param index index of the page + /// \param enabled an enable flag void setPageEnabled(int index, bool enabled); + + /// Set page name + /// \param index index of the page + /// \param text a name of the page void setPageName(int index, const QString & text); + + /// Set page tooltip + /// \param index index of the page + /// \param toolTip a tooltip of the page void setPageToolTip(int index, const QString & toolTip); public slots: + /// Set current page by index + /// \param index index of the page void setCurrentIndex(int index); signals: + /// Emitted on current page change void currentPageChanged(int); protected: + /// Update widget void refresh(); private: + /// Layout QVBoxLayout* myMainLay; + + /// Combo box QComboBox* myCombo; + + /// List of pages QWidgetList myCases; }; diff --git a/src/NewGeom/NewGeom_DataModel.h b/src/NewGeom/NewGeom_DataModel.h index 1024f275d..5f6f9519d 100644 --- a/src/NewGeom/NewGeom_DataModel.h +++ b/src/NewGeom/NewGeom_DataModel.h @@ -9,22 +9,51 @@ class NewGeom_Module; +/** +* \ingroup Salome +* A Data Model class provides a connection of SALOME data structure and OpenParts application data model +*/ class NewGeom_EXPORT NewGeom_DataModel : public LightApp_DataModel { Q_OBJECT public: + /// Constructor + /// \param theModule a module instance NewGeom_DataModel(NewGeom_Module* theModule); virtual ~NewGeom_DataModel(); + /// Open a data file + /// \param thePath a path to the directory + /// \param theStudy a current study + /// \param theFiles a list of files to open virtual bool open(const QString& thePath, CAM_Study* theStudy, QStringList theFiles); + + /// Save module data to file + /// \param theFiles list of created files virtual bool save(QStringList& theFiles); + + /// Save module data to a file + /// \param thePath a path to the directory + /// \param theStudy a current study + /// \param theFiles a list of files to open virtual bool saveAs(const QString& thePath, CAM_Study* theStudy, QStringList& theFiles); + + /// Close data structure virtual bool close(); + + /// Create data structure + /// \param theStudy a current study virtual bool create(CAM_Study* theStudy); + /// Returns True if the data structure has been modified virtual bool isModified() const; + + /// Returns True if the data structure is already saved virtual bool isSaved() const; + /// Update data object + /// \param theObj an data object + /// \param theStudy a current study virtual void update(LightApp_DataObject* theObj = 0, LightApp_Study* theStudy = 0); protected: @@ -35,8 +64,12 @@ protected: static void removeDirectory(const QString& theDirectoryName); private: + /// Pat to a study file QString myStudyPath; - QString myTmpDirectory; /// a path to the temporary directory, created by opening a document file + + /// a path to the temporary directory, created by opening a document file + QString myTmpDirectory; + /// it should be created because the files reading is postponed in the module. The directory // should be removed after the model document is closed. NewGeom_Module* myModule; diff --git a/src/XGUI/XGUI_ActionsMgr.h b/src/XGUI/XGUI_ActionsMgr.h index 3101cb0bd..8007e9794 100644 --- a/src/XGUI/XGUI_ActionsMgr.h +++ b/src/XGUI/XGUI_ActionsMgr.h @@ -23,11 +23,17 @@ class XGUI_OperationMgr; class ModuleBase_Operation; class QAction; +/** +* \ingroup GUI +* A class for management of actions (features) activation/deactivation +*/ class XGUI_EXPORT XGUI_ActionsMgr : public QObject, public Events_Listener { Q_OBJECT public: + /// Constructor + /// \param theWorkshop an instance of workshop XGUI_ActionsMgr(XGUI_Workshop* theWorkshop); virtual ~XGUI_ActionsMgr(); @@ -35,13 +41,20 @@ Q_OBJECT //! Please note that nested commands in the Salome mode (No AppElements_Command, pure QActions) //! won't be extracted and should be added manually using the addNestedCommands method. void addCommand(QAction* theCmd); + //! Sets relation between the command (with given Id) and it's nested actions. void addNestedCommands(const QString& theId, const QStringList& theCommands); + //! Returns list of nested commands by parent command Id + //! \param theId a parent command Id QStringList nestedCommands(const QString& theId) const; + /// Returns True if the given Id is an Id of nested command + /// \param theId an Id to check bool isNested(const QString& theId) const; + /// Registers shortcut (key sequence) for the command triggering + /// \param theKeySequence a key sequence to register QKeySequence registerShortcut(const QString& theKeySequence); //! Redefinition of Events_Listener method diff --git a/src/XGUI/XGUI_ObjectsBrowser.h b/src/XGUI/XGUI_ObjectsBrowser.h index a52c84454..93cc131be 100644 --- a/src/XGUI/XGUI_ObjectsBrowser.h +++ b/src/XGUI/XGUI_ObjectsBrowser.h @@ -15,10 +15,16 @@ class XGUI_DocumentDataModel; class QLineEdit; +/** +* \ingroup GUI +* Implementation of Data Tree object for Object Browser +*/ class XGUI_DataTree : public QTreeView { Q_OBJECT public: + /// Constructor + /// \param theParent a parent widget XGUI_DataTree(QWidget* theParent); virtual ~XGUI_DataTree(); @@ -28,24 +34,32 @@ Q_OBJECT return mySelectedData; } + /// Returns current data model XGUI_DocumentDataModel* dataModel() const; signals: //! Emited when selection is changed void selectionChanged(); + + //! Emited when active part changed void activePartChanged(ObjectPtr thePart); //! Emited on context menu request void contextMenuRequested(QContextMenuEvent* theEvent); public slots: + /// Clear content of data tree virtual void clear(); protected slots: + /// Commit modified data (used for renaming of objects) virtual void commitData(QWidget* theEditor); protected: + /// Redefinition of virtual method virtual void mouseDoubleClickEvent(QMouseEvent* theEvent); + + /// Redefinition of virtual method virtual void contextMenuEvent(QContextMenuEvent* theEvent); private slots: @@ -65,6 +79,8 @@ class XGUI_EXPORT XGUI_ObjectsBrowser : public QWidget { Q_OBJECT public: + /// Constructor + /// \param theParent a parent widget XGUI_ObjectsBrowser(QWidget* theParent); virtual ~XGUI_ObjectsBrowser(); @@ -80,6 +96,8 @@ Q_OBJECT return myObjectsList; } + /// Set selected list of objects + /// \param theObjects list of objects to select void setObjectsSelected(const QObjectPtrList& theObjects); //! Returns currently selected indexes @@ -97,11 +115,14 @@ Q_OBJECT //! Activates currently selected part. Signal activePartChanged will not be sent void activatePart(const ResultPartPtr& thePart); + /// Rebuild data tree void rebuildDataTree(); + /// Process application event + /// \param theMessage an event message void processEvent(const std::shared_ptr& theMessage); - // Resets the object browser into initial state + /// Resets the object browser into initial state void clearContent(); signals: @@ -115,16 +136,26 @@ signals: void contextMenuRequested(QContextMenuEvent* theEvent); protected: + /// Redefinition of virtual method virtual bool eventFilter(QObject* obj, QEvent* theEvent); private slots: + /// Activate part + /// \param thePart a part to activate void onActivePartChanged(ObjectPtr thePart); + + /// Show context menu + /// \param theEvent a context menu event void onContextMenuRequested(QContextMenuEvent* theEvent); + + /// Show context menu on upper label + /// \param thePnt a position of context menu void onLabelContextMenuRequested(const QPoint& thePnt); //! Called on Edit command request void onEditItem(); + /// Process selection changed event void onSelectionChanged(); private: -- 2.39.2