From 1fb822f60336a1ff89c8045ed4486682bfbc21a2 Mon Sep 17 00:00:00 2001 From: sbh Date: Wed, 28 Jan 2015 15:34:31 +0300 Subject: [PATCH] Documentation for config module updated --- src/Config/Config_AttributeMessage.h | 22 ++++++--- src/Config/Config_Common.h | 4 ++ src/Config/Config_FeatureMessage.h | 56 ++++++++++++++++------ src/Config/Config_FeatureReader.h | 1 + src/Config/Config_ModuleReader.h | 33 ++++++++----- src/Config/Config_PointerMessage.h | 5 +- src/Config/Config_Prop.h | 31 +++++++----- src/Config/Config_PropManager.h | 35 +++++++------- src/Config/Config_SelectionFilterMessage.h | 8 ++++ src/Config/Config_ValidatorMessage.h | 11 ++++- src/Config/Config_WidgetAPI.h | 32 ++++++++----- src/Config/Config_WidgetReader.h | 6 +++ src/Config/Config_XMLReader.cpp | 37 -------------- src/Config/Config_XMLReader.h | 49 +++++++++++++++---- src/XGUI/XGUI_Workshop.cpp | 6 +-- 15 files changed, 209 insertions(+), 127 deletions(-) diff --git a/src/Config/Config_AttributeMessage.h b/src/Config/Config_AttributeMessage.h index 9272a7b6e..bfb9b64b1 100644 --- a/src/Config/Config_AttributeMessage.h +++ b/src/Config/Config_AttributeMessage.h @@ -18,31 +18,41 @@ */ class Config_AttributeMessage : public Events_Message { - std::string myAttributeId; //Feature unique id - std::string myFeatureId; //Feature unique id - bool myIsObligatory; - bool myIsConcealment; + std::string myAttributeId; ///< Attribute's unique id + std::string myFeatureId; ///< Attribute's feature's unique id + bool myIsObligatory; ///< Required to be set by user, else it's feature is invalid. + bool myIsConcealment; ///< If true, conceals features used as input public: - // Same event as Config_FeatureMessage::MODEL_EVENT() + /// Same event as Config_FeatureMessage::MODEL_EVENT() inline static const char* MODEL_EVENT() { return Config_FeatureMessage::MODEL_EVENT(); } - //const Events_ID theID, const void* theSender = 0 + /// Constructor CONFIG_EXPORT Config_AttributeMessage(const Events_ID theId, const void* theParent = 0); + /// Destructor CONFIG_EXPORT virtual ~Config_AttributeMessage(); //Auto-generated getters/setters + /// Returns attribute's unique id CONFIG_EXPORT const std::string& attributeId() const; + /// Returns attribute's feature's unique id CONFIG_EXPORT const std::string& featureId() const; + /// Returns true if attribute is obligatory: + /// Required to be set by user, else it's feature is invalid. CONFIG_EXPORT bool isObligatory() const; + /// Returns true if attribute should conceal input features CONFIG_EXPORT bool isConcealment() const; + /// Set attribute's unique id CONFIG_EXPORT void setAttributeId(const std::string& theId); + /// Set attribute's feature's unique id CONFIG_EXPORT void setFeatureId(const std::string& id); + /// Returns attribute's concealment state CONFIG_EXPORT void setConcealment(bool isConcealment); + /// Returns attribute's obligatory state CONFIG_EXPORT void setObligatory(bool isObligatory); }; diff --git a/src/Config/Config_Common.h b/src/Config/Config_Common.h index c1379efe6..e6d641d2e 100644 --- a/src/Config/Config_Common.h +++ b/src/Config/Config_Common.h @@ -98,6 +98,10 @@ CONFIG_EXPORT bool getBooleanAttribute(xmlNodePtr theNode, * Should be used for case insensitive string matching. */ CONFIG_EXPORT std::string normalize(const char* theString); +/*! + * Returns normalized (lower case) version of string. + * Should be used for case insensitive string matching. + */ CONFIG_EXPORT std::string normalize(const std::string& theString); #endif diff --git a/src/Config/Config_FeatureMessage.h b/src/Config/Config_FeatureMessage.h index 28ae49c38..a56d7253a 100644 --- a/src/Config/Config_FeatureMessage.h +++ b/src/Config/Config_FeatureMessage.h @@ -18,20 +18,20 @@ */ class Config_FeatureMessage : public Events_Message { - std::string myId; //Feature unique id - std::string myText; //Represents action's text - std::string myTooltip; //Represents action's tooltip - std::string myIcon; //Represents action's icon - std::string myKeysequence; //Represents action's key sequence + std::string myId; ///& featuresInFiles() const; - + /// Returns module name: an xml attribute from the root of the plugins.xml: + /// e.g CONFIG_EXPORT std::string getModuleName(); - + /// Detects type of the given plugin and loads it using loadLibrary or loadScript. CONFIG_EXPORT static void loadPlugin(const std::string& thePluginName); /// loads the library with specific name, appends "lib*.dll" or "*.so" depending on the platform CONFIG_EXPORT static void loadLibrary(const std::string& theLibName); /// loads the python module with specified name CONFIG_EXPORT static void loadScript(const std::string& theFileName); - // extends set of modules, which will be used for dependency - // checking (if there is no required module in the set, a plugin will not be loaded) + /*! + * Extends set of modules, used for dependency checking (if there is no + * required module in the set, a plugin will not be loaded) + */ CONFIG_EXPORT static void addDependencyModule(const std::string& theModuleName); protected: - void processNode(xmlNodePtr aNode); - bool processChildren(xmlNodePtr aNode); - + /// Recursively process the given xmlNode + virtual void processNode(xmlNodePtr aNode); + /// Defines if the reader should process children of the given node + virtual bool processChildren(xmlNodePtr aNode); + /// check if dependencies of the given node are in the list of loaded modules bool hasRequiredModules(xmlNodePtr aNode) const; + /// reads info about plugin's features from plugin xml description std::list importPlugin(const std::string& thePluginLibrary, const std::string& thePluginFile); + /// stores information about plugin in the internal cache std::string addPlugin(const std::string& aPluginLibrary, const std::string& aPluginScript, const std::string& aPluginConf); private: - std::map myFeaturesInFiles; - static std::map myPluginTypes; - static std::set myDependencyModules; - const char* myEventGenerated; + std::map myFeaturesInFiles; ///< a feature name is key, a file is value + static std::map myPluginTypes; ///< a plugin name is key, a plugin type is value + static std::set myDependencyModules; ///< set of loaded modules + const char* myEventGenerated; ///< gives ability to send Feature_Messages to various listeners }; #endif /* CONFIG_XMLMODULEREADER_H_ */ diff --git a/src/Config/Config_PointerMessage.h b/src/Config/Config_PointerMessage.h index 4edb8c31e..aafa6b036 100644 --- a/src/Config/Config_PointerMessage.h +++ b/src/Config/Config_PointerMessage.h @@ -20,14 +20,17 @@ class CONFIG_EXPORT Config_PointerMessage : public Events_Message { public: + /// Constructor Config_PointerMessage(const Events_ID theId, const void* theParent = 0); virtual ~Config_PointerMessage(); + /// Returns pointer to an object void* pointer() const; + /// Sets pointer to an object void setPointer(void* pointer); private: - void* myPointer; + void* myPointer; ///< Pointer to an object }; #endif /* PARTSET_MESSAGE_H_ */ diff --git a/src/Config/Config_Prop.h b/src/Config/Config_Prop.h index b9252a8c0..1cf0c0c53 100644 --- a/src/Config/Config_Prop.h +++ b/src/Config/Config_Prop.h @@ -17,6 +17,7 @@ class Config_Prop { public: + /// Type of stored property enum PropType { Disabled, @@ -61,59 +62,63 @@ class Config_Prop myDefaultValue = theDefaultValue; } + /// Get name of section std::string section() const { return mySection; } + /// Get name of property std::string name() const { return myName; } - + /// Get title of property std::string title() const { return myTitle; } + /// Set title of property void setTitle(const std::string& theTitle) { myTitle = theTitle; } - + /// Get type of property PropType type() const { return myType; } + /// Set type of property void setType(PropType theType) { myType = theType; } - + /// Get property's value in string format std::string value() const { return myValue; } - + /// Set property's value in string format CONFIG_EXPORT void setValue(const std::string& theValue); - + /// Get default value of property std::string defaultValue() const { return myDefaultValue; } - + /// Set default value of property CONFIG_EXPORT void setDefaultValue(const std::string& theValue); - + /// Alows to compare Config_Prop with each other bool operator==(const Config_Prop* theProp) const { return (mySection == theProp->section()) && (myName == theProp->name()); } private: - std::string mySection; - std::string myName; - std::string myTitle; - PropType myType; - std::string myValue; - std::string myDefaultValue; + std::string mySection; ///< Name of section + std::string myName; ///< Name of property + std::string myTitle; ///< Title of property + PropType myType; ///< Type of property + std::string myValue; // Value in string format + std::string myDefaultValue; // Default value }; typedef std::list Config_Properties; diff --git a/src/Config/Config_PropManager.h b/src/Config/Config_PropManager.h index 40e2f762a..a875fbf6f 100644 --- a/src/Config/Config_PropManager.h +++ b/src/Config/Config_PropManager.h @@ -21,7 +21,6 @@ class Config_PropManager /** * Registers property parameters - * \param theOwnerId - name of owner (name of plugin for example) * \param theSection - name of section (domain of using) of the property. * \param theName - name (title) of the value. * \param theType - type of the value. @@ -30,33 +29,35 @@ class Config_PropManager */ CONFIG_EXPORT static Config_Prop* registerProp(const std::string& theSection, const std::string& theName, const std::string& theTitle, Config_Prop::PropType theType, const std::string& theDefValue = ""); - + //! Finds property in the given section by the given name, if property not found returns NULL CONFIG_EXPORT static Config_Prop* findProp( const std::string& theSection, const std::string& theName); - + //! Returns std::list of all existing properies CONFIG_EXPORT static Config_Properties getProperties(); - //! Returns list of registered section names. CONFIG_EXPORT static std::list getSections(); - //! Returns list of properties by its owner and section. CONFIG_EXPORT static Config_Properties getProperties(const std::string& theSection); //! Returns value of the property by its owner, section, and name - CONFIG_EXPORT static std::string string( - const std::string& theSection, const std::string& theName, const std::string& theDefault); - - CONFIG_EXPORT static std::vector color( - const std::string& theSection, const std::string& theName, const std::string& theDefault); - - CONFIG_EXPORT static int integer( - const std::string& theSection, const std::string& theName, const std::string& theDefault); - - CONFIG_EXPORT static double real( - const std::string& theSection, const std::string& theName, const std::string& theDefault); + CONFIG_EXPORT static std::string string(const std::string& theSection, + const std::string& theName, + const std::string& theDefault); + //! Returns color by given section and name as 3-element vector {r,g,b}. + CONFIG_EXPORT static std::vector color(const std::string& theSection, + const std::string& theName, + const std::string& theDefault); + //! Returns integer by given section and name + CONFIG_EXPORT static int integer(const std::string& theSection, + const std::string& theName, + const std::string& theDefault); + //! Returns real by given section and name + CONFIG_EXPORT static double real(const std::string& theSection, + const std::string& theName, + const std::string& theDefault); private: - CONFIG_EXPORT static Config_Properties myProps; + CONFIG_EXPORT static Config_Properties myProps; ///< List of all stored properties }; #endif diff --git a/src/Config/Config_SelectionFilterMessage.h b/src/Config/Config_SelectionFilterMessage.h index fcc54a010..1d3e6d98d 100644 --- a/src/Config/Config_SelectionFilterMessage.h +++ b/src/Config/Config_SelectionFilterMessage.h @@ -34,14 +34,22 @@ class Config_SelectionFilterMessage : public Events_Message CONFIG_EXPORT Config_SelectionFilterMessage(const Events_ID theId, const void* theParent = 0); CONFIG_EXPORT virtual ~Config_SelectionFilterMessage(); + //! Get id of the filter CONFIG_EXPORT const std::string& selectionFilterId() const; + //! Get id of a feature to which the filter belongs to CONFIG_EXPORT const std::string& featureId() const; + //! Get id of an attribute to which the filter belongs to CONFIG_EXPORT const std::string& attributeId() const; + //! Get filter parameters CONFIG_EXPORT const std::list& parameters() const; + //! Set id of the filter CONFIG_EXPORT void setSelectionFilterId(const std::string& theId); + //! Set id of a feature to which the filter belongs to CONFIG_EXPORT void setFeatureId(const std::string& theId); + //! Set id of an attribute to which the filter belongs to CONFIG_EXPORT void setAttributeId(const std::string& theId); + //! Get filter parameters CONFIG_EXPORT void setFilterParameters(const std::list& parameters); }; diff --git a/src/Config/Config_ValidatorMessage.h b/src/Config/Config_ValidatorMessage.h index d137097f9..a0e410c15 100644 --- a/src/Config/Config_ValidatorMessage.h +++ b/src/Config/Config_ValidatorMessage.h @@ -34,17 +34,24 @@ class Config_ValidatorMessage : public Events_Message CONFIG_EXPORT Config_ValidatorMessage(const Events_ID theId, const void* theParent = 0); CONFIG_EXPORT virtual ~Config_ValidatorMessage(); - //CONFIG_EXPORT static const char* UID() const; - + //! Get id of the filter CONFIG_EXPORT const std::string& validatorId() const; + //! Get id of a feature to which the filter belongs to CONFIG_EXPORT const std::string& featureId() const; + //! Get id of an attribute to which the filter belongs to CONFIG_EXPORT const std::string& attributeId() const; + //! Get filter parameters CONFIG_EXPORT const std::list& parameters() const; + //! Returns true if validator id is not empty CONFIG_EXPORT bool isValid() const; + //! Set id of the filter CONFIG_EXPORT void setValidatorId(const std::string& theId); + //! Set id of a feature to which the filter belongs to CONFIG_EXPORT void setFeatureId(const std::string& theId); + //! Set id of an attribute to which the filter belongs to CONFIG_EXPORT void setAttributeId(const std::string& theId); + //! Get filter parameters CONFIG_EXPORT void setValidatorParameters(const std::list& parameters); }; diff --git a/src/Config/Config_WidgetAPI.h b/src/Config/Config_WidgetAPI.h index 2c2cd9c71..fa11e44e1 100644 --- a/src/Config/Config_WidgetAPI.h +++ b/src/Config/Config_WidgetAPI.h @@ -36,37 +36,47 @@ class CONFIG_EXPORT Config_WidgetAPI public: virtual ~Config_WidgetAPI(); + //! Returns name of widget's node (attribute) std::string widgetType() const; + //! Returns true if widget has container type, which means it able to contain other widgets bool isContainerWidget() const; + //! Returns true if widget has page type; + //! Page is container widget with combo box control to switch between pages bool isPagedWidget() const; + //! Returns id of current widget std::string widgetId() const; + //! Returns icon of current widget std::string widgetIcon() const; + //! Returns text for label of current widget std::string widgetLabel() const; + //! Returns text for tooltip of current widget std::string widgetTooltip() const; - + //! Returns a custom property of current widget std::string getProperty(const char* thePropName) const; - /// Checks if the XML representation of widget has given attribute, - /// if yes - returns it's bool value, if no, or if the value can not - /// be converted to bool - returns theDefault. - /// \param theAttributeName attribute to check - /// \param theDefault default value on bad data - /// \return the boolean result + /*! Checks if the XML representation of widget has given attribute, + * if yes - returns it's bool value, if no, or if the value can not + * be converted to bool - returns theDefault. + * \param theAttributeName attribute to check + * \param theDefault default value on bad data + * \return the boolean result + */ bool getBooleanAttribute(const char* theAttributeName, bool theDefault) const; - bool isComputedDefault() const; - protected: /// These fields are accessible for ModuleBase_WidgetFactory only Config_WidgetAPI(std::string theRawXml); + //! Pass to the next (sibling) node of widget's xml definition. If impossible, returns false bool toNextWidget(); + //! Pass into the child node of widget's xml definition. If impossible, returns false bool toChildWidget(); + //! Pass into the parent node of widget's xml definition. If impossible, returns false bool toParentWidget(); private: - xmlDocPtr myDoc; - xmlNodePtr myCurrentNode; + xmlDocPtr myDoc; //!< Pointer to the root of widget's xml definition + xmlNodePtr myCurrentNode; //!< Pointer to the current node in the widget's xml definition friend class ModuleBase_WidgetFactory; }; diff --git a/src/Config/Config_WidgetReader.h b/src/Config/Config_WidgetReader.h index 783f2aa45..f36f95140 100644 --- a/src/Config/Config_WidgetReader.h +++ b/src/Config/Config_WidgetReader.h @@ -27,13 +27,19 @@ class Config_WidgetReader : public Config_XMLReader CONFIG_EXPORT Config_WidgetReader(const std::string& theXmlFile); CONFIG_EXPORT virtual ~Config_WidgetReader(); + /// Extract feature's widget configuration from local cache, stored on node processing CONFIG_EXPORT std::string featureWidgetCfg(const std::string& theFeatureName); + /// Extract feature's description from local cache, stored on node processing CONFIG_EXPORT std::string featureDescription(const std::string& theFeatureName); protected: + /// Overloaded method. Defines how to process each node void processNode(xmlNodePtr theNode); + /// Overloaded method. Defines if the given node should be parsed recursively bool processChildren(xmlNodePtr theNode); + /// Extracts xml definition of the given node and it's children std::string dumpNode(xmlNodePtr theNode); + /// Replace all "source" nodes with their content (used before dumping nodes) void resolveSourceNodes(xmlNodePtr theNode); private: diff --git a/src/Config/Config_XMLReader.cpp b/src/Config/Config_XMLReader.cpp index a29eaab64..03af8f4c7 100644 --- a/src/Config/Config_XMLReader.cpp +++ b/src/Config/Config_XMLReader.cpp @@ -64,22 +64,12 @@ Config_XMLReader::~Config_XMLReader() xmlFreeDoc(myXmlDoc); } -/*! - * Read all nodes in associated xml file, - * recursively if processChildren(xmlNode) is true for the xmlNode. - * For each read node the processNode will be called. - */ void Config_XMLReader::readAll() { xmlNodePtr aRoot = findRoot(); readRecursively(aRoot); } -/*! - * Allows to customize reader's behavior for a node. Virtual. - * The default impl does nothing. (In debug mode prints - * some info) - */ void Config_XMLReader::processNode(xmlNodePtr theNode) { if (isNode(theNode, NODE_SOURCE, NULL)) { @@ -96,19 +86,11 @@ void Config_XMLReader::processNode(xmlNodePtr theNode) } } -/*! - * Defines which nodes should be processed recursively. Virtual. - * The default impl is to read all nodes. - */ bool Config_XMLReader::processChildren(xmlNodePtr aNode) { return true; } -/*! - * Returns xmlNodePtr to the root of reader's document - * or NULL if not found - */ xmlNodePtr Config_XMLReader::findRoot() { if (myXmlDoc == NULL) { @@ -130,11 +112,6 @@ xmlNodePtr Config_XMLReader::findRoot() return aRoot; } -/*! - * Calls processNode() for each child (for some - recursively) - * of the given node. - * \sa ReadAll() - */ void Config_XMLReader::readRecursively(xmlNodePtr theParent) { if (!theParent) @@ -152,17 +129,11 @@ void Config_XMLReader::readRecursively(xmlNodePtr theParent) } } -/*! - * void* -> xmlNodePtr - */ xmlNodePtr Config_XMLReader::node(void* theNode) { return static_cast(theNode); } -/*! - * Gets xml node name - */ std::string Config_XMLReader::getNodeName(xmlNodePtr theNode) { std::string result = ""; @@ -173,10 +144,6 @@ std::string Config_XMLReader::getNodeName(xmlNodePtr theNode) return result; } -/*! - * Retrieves all the necessary info from the validator node. - * Sends ValidatorLoaded event - */ void Config_XMLReader::processValidator(xmlNodePtr theNode) { Events_ID aValidatoEvent = Events_Loop::eventByName(EVENT_VALIDATOR_LOADED); @@ -198,10 +165,6 @@ void Config_XMLReader::processValidator(xmlNodePtr theNode) aEvLoop->send(aMessage); } -/*! - * Retrieves all the necessary info from the SelectionFilter node. - * Sends SelectionFilterLoaded event - */ void Config_XMLReader::processSelectionFilter(xmlNodePtr theNode) { Events_ID aFilterEvent = Events_Loop::eventByName(EVENT_SELFILTER_LOADED); diff --git a/src/Config/Config_XMLReader.h b/src/Config/Config_XMLReader.h index 412af81a2..1a75184b6 100644 --- a/src/Config/Config_XMLReader.h +++ b/src/Config/Config_XMLReader.h @@ -29,6 +29,7 @@ struct _xmlDoc; /*! * \class Config_XMLReader + * \ingroup Config * \brief Base class for all libxml readers. Provides high-level API * for all xml operations. */ @@ -37,29 +38,57 @@ class Config_XMLReader public: CONFIG_EXPORT Config_XMLReader(const std::string& theXmlFile); CONFIG_EXPORT virtual ~Config_XMLReader(); - + /*! + * Read all nodes in associated xml file, + * recursively if processChildren(xmlNode) is true for the xmlNode. + * For each read node the processNode will be called. + */ CONFIG_EXPORT void readAll(); - - public: + /*! + * Returns xmlNodePtr to the root of reader's document + * or NULL if not found + */ CONFIG_EXPORT xmlNodePtr findRoot(); protected: + /*! + * \brief Allows to customize reader's behavior for a node. Virtual. + * The default implementation process "source", "validator" and + * "selection_filter" nodes. + */ virtual void processNode(xmlNodePtr aNode); + /*! + * \brief Defines which nodes should be processed recursively. Virtual. + * The default impl is to read all nodes. + */ virtual bool processChildren(xmlNodePtr aNode); - + /*! + * Calls processNode() for each child (for some - recursively) + * of the given node. + * \sa ReadAll() + */ void readRecursively(xmlNodePtr theParent); - + /*! + * \brief void* -> xmlNodePtr + */ xmlNodePtr node(void* theNode); + /// Gets xml node name std::string getNodeName(xmlNodePtr theNode); + /*! + * \brief Retrieves all the necessary info from the validator node. + * Sends ValidatorLoaded event + */ void processValidator(xmlNodePtr theNode); + /*! + * \brief Retrieves all the necessary info from the SelectionFilter node. + * Sends SelectionFilterLoaded event + */ void processSelectionFilter(xmlNodePtr theNode); protected: - std::string myCurrentFeature; - - protected: - std::string myDocumentPath; - xmlDocPtr myXmlDoc; + std::string myCurrentFeature; ///< Name of currently processed feature + std::string myDocumentPath; ///< Path to the xml document + xmlDocPtr myXmlDoc; ///< Root of the xml document }; #endif /* CONFIG_XMLREADER_H_ */ diff --git a/src/XGUI/XGUI_Workshop.cpp b/src/XGUI/XGUI_Workshop.cpp index 77acb88d5..742b0adc0 100644 --- a/src/XGUI/XGUI_Workshop.cpp +++ b/src/XGUI/XGUI_Workshop.cpp @@ -1095,7 +1095,7 @@ void XGUI_Workshop::createDockWidgets() connect(myPropertyPanel, SIGNAL(noMoreWidgets()), myModule, SLOT(onNoMoreWidgets())); aDesktop->addDockWidget(Qt::LeftDockWidgetArea, myPropertyPanel); - hidePropertyPanel(); //tabifyDockWidget(aObjDock, myPropertyPanel); myPropertyPanel->installEventFilter(myOperationMgr); @@ -1115,7 +1115,7 @@ void XGUI_Workshop::createDockWidgets() void XGUI_Workshop::showPropertyPanel() { QAction* aViewAct = myPropertyPanel->toggleViewAction(); - //setEnabled(true); myPropertyPanel->show(); myPropertyPanel->raise(); @@ -1125,7 +1125,7 @@ void XGUI_Workshop::showPropertyPanel() void XGUI_Workshop::hidePropertyPanel() { QAction* aViewAct = myPropertyPanel->toggleViewAction(); - //setEnabled(false); myPropertyPanel->hide(); } -- 2.39.2