From d81c8d209feddcdc057076ca9e240f0a2b89a00b Mon Sep 17 00:00:00 2001 From: Sabine Schmaltz Date: Tue, 18 Mar 2014 23:36:32 +0100 Subject: [PATCH] improvements to the updated comments --HG-- branch : develop --- src/xml/vdomdocument.h | 426 ++++++++++++++++++++++------------------- 1 file changed, 224 insertions(+), 202 deletions(-) diff --git a/src/xml/vdomdocument.h b/src/xml/vdomdocument.h index e808e614e..25bb08695 100644 --- a/src/xml/vdomdocument.h +++ b/src/xml/vdomdocument.h @@ -6,8 +6,8 @@ ** ** @brief ** @copyright - ** This source code is part of the Valentine project, a pattern making - ** program, whose allow create and modeling patterns of clothing. + ** This source code is part of the Valentina project, a pattern making + ** program that allows creating and modelling patterns of clothing. ** Copyright (C) 2013 Valentina project ** All Rights Reserved. ** @@ -41,7 +41,8 @@ namespace Document { /** - * @brief The Document enum types parse. + * @brief Flags to determine the parsing mode in VDomDocument::Parse() and + * related functions. */ enum Document { LiteParse, FullParse}; Q_DECLARE_FLAGS(Documents, Document) @@ -54,403 +55,424 @@ Q_DECLARE_OPERATORS_FOR_FLAGS(Document::Documents) #endif /** - * @brief The VDomDocument class working with pattern file. + * @brief The VDomDocument class represents a Valentina document (.val file). + * + * A Valentina document describes the construction of a sewing pattern. The + * information is stored in XML format. By parsing a VDomDocument, the contained + * pattern is rendered to a Valentina graphics scene (VMainGraphicsScene). + * + * A sewing pattern consists of zero or more increments and one + * or more pattern pieces. + * + * An increment is an auxiliary variable that is calculated from regular measurement + * variables (that belong to the standard measurements table). Increments are used to + * create a graduation schema for the sewing pattern. + * + * A pattern piece contains + * 1) auxiliary pattern construction elements (calculation), + * 2) pattern construction elements (modeling), and + * 3) special markers, e.g. seam allowances (details). + * Of these, 2) and 3) are visible in the final pattern (draw mode 'Modeling'), + * 1) is only displayed when editing (draw mode 'Calculation') the pattern. */ class VDomDocument : public QObject, public QDomDocument { Q_OBJECT public: - /** - * @brief VDomDocument constructor. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, QObject *parent = 0); - /** - * @brief VDomDocument constructor. - * @param name pattern peace name. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(const QString& name, VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, - QObject *parent = 0); - /** - * @brief VDomDocument constructor. - * @param doc dom document container type. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(const QDomDocumentType& doctype, VContainer *data, QComboBox *comboBoxDraws, - Draw::Draws *mode, QObject *parent = 0); - ~VDomDocument(){} /** - * @brief elementById find element by id. + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent + */ + VDomDocument(VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, QObject *parent = 0); + /** + * @param name pattern piece name + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent + */ + VDomDocument(const QString& name, VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, + QObject *parent = 0); + /** + * @param doctype dom document container type + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent + */ + VDomDocument(const QDomDocumentType& doctype, VContainer *data, QComboBox *comboBoxDraws, + Draw::Draws *mode, QObject *parent = 0); + ~VDomDocument(){} + /** + * @brief Finds an element by id. * @param id value id attribute. * @return dom element. */ QDomElement elementById(const QString& id); /** - * @brief removeAllChilds remove all tag childs. - * @param element tag. + * @brief Removes all children of a given element tag. RENAME: removeAllChildren! + * @param element tag */ void removeAllChilds(QDomElement &element); /** - * @brief CreateEmptyFile create minimal empty file. + * @brief Create a minimal empty file. */ void CreateEmptyFile(); /** - * @brief ChangeActivDraw set new pattern peace name. - * @param name new name. - * @param parse parser file mode. + * @brief Select pattern piece based on name. RENAME: ChangeActiveDraw? ChangeActivePatternPiece? + * @param name pattern piece name + * @param parse parsing mode */ void ChangeActivDraw(const QString& name, const Document::Documents &parse = Document::FullParse); /** - * @brief GetNameActivDraw return current pattern peace name. - * @return pattern peace name. + * @brief Get selected pattern piece name. RENAME: GetNameOfActiveDraw? GetNameOfActivePatternPiece? + * @return name of the active pattern piece */ inline QString GetNameActivDraw() const {return nameActivDraw;} /** - * @brief GetActivDrawElement return draw tag for current pattern peace. - * @param element draw tag. - * @return true if found. + * @brief Finds the draw element of the selected pattern piece and returns it by reference. RENAME: GetActiveDrawElement? + * @param element the returned draw element -- not used as input + * @return true if found */ bool GetActivDrawElement(QDomElement &element); /** - * @brief GetActivCalculationElement return calculation tag for current pattern peace. - * @param element calculation tag. - * @return true if found. + * @brief Finds the calculation element for the selected pattern piece and returns it by reference. RENAME: GetActiveCalculationElement? + * @param element the returned calculation element -- not used as input + * @return true if found */ bool GetActivCalculationElement(QDomElement &element); /** - * @brief GetActivModelingElement return modeling tag for current pattern peace. - * @param element modeling tag - * @return true if found. + * @brief Finds the modeling element for the selected pattern piece and returns it by reference. RENAME: GetActiveModelingElement? + * @param element the returned modeling element -- not used as input + * @return true if found */ bool GetActivModelingElement(QDomElement &element); /** - * @brief GetActivDetailsElement return details tag for current pattern peace. - * @param element details tag. - * @return true if found. + * @brief Finds the details element for the selected pattern piece and returns it by reference. RENAME: GetActiveDetailsElement? + * @param element the returned details element -- not used as input + * @return true if found */ bool GetActivDetailsElement(QDomElement &element); /** - * @brief appendDraw add new pattern peace structure to the file. - * @param name pattern peace name. - * @return true if success. + * @brief Adds a new pattern piece to the document. NOTE: inconsistent capitalization + * @param name pattern piece name. + * @return true if successful */ bool appendDraw(const QString& name); /** - * @brief SetNameDraw change current pattern peace. - * @param name pattern peace name. - * @return true if success. + * @brief Sets the name of the selected pattern piece. RENAME: SetNameOfActiveDraw! + * @param name pattern piece name. + * @return true if successful */ bool SetNameDraw(const QString& name); /** - * @brief Parse parse file. - * @param parse parser file mode. - * @param sceneDraw pointer to draw scene. - * @param sceneDetail pointer to details scene. + * @brief Parse the document, resulting in a rendering of the pattern in the graphics scenes. + * @param parse parsing mode + * @param sceneDraw pointer to draw scene + * @param sceneDetail pointer to details scene */ void Parse(const Document::Documents &parse, VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail); /** - * @brief getTools return list of tools pointers. - * @return list. + * @brief Return the list of tool pointers. When we create lines, points, curves on scene we + * use tools. This structure keeps the pointers to those tools. + * @return list of tool pointers */ - inline QHash* getTools() {return &tools;} + inline QHash* getTools() {return &tools;} // NOTE: inconsistent capitalization /** - * @brief getTool return tool from tool list. - * @param id tool id. - * @return tool. + * @brief Get a tool from the tool list by id. + * @param id tool id + * @return tool */ - VDataTool* getTool(const qint64 &id); + VDataTool* getTool(const qint64 &id); // NOTE: inconsistent capitalization /** - * @brief getHistory return list with list of history records. - * @return list of history records. + * @brief Return a list of history record lists. The history keeps track of the tools the user used + * to create the pattern piece. + * @return list of history record lists */ - inline QVector *getHistory() {return &history;} + inline QVector *getHistory() {return &history;} // NOTE: inconsistent capitalization /** - * @brief getCursor return cursor. - * @return cursor. + * @brief Returns the cursor. Here, the cursor is the id of the tool after which a + * new object will be added. + * @return cursor */ - inline qint64 getCursor() const {return cursor;} + inline qint64 getCursor() const {return cursor;} // NOTE: inconsistent capitalization /** - * @brief setCursor set cursor. - * @param value cursor. + * @brief Set the cursor. + * @param value cursor */ - void setCursor(const qint64 &value); + void setCursor(const qint64 &value); // NOTE: inconsistent capitalization /** - * @brief setCurrentData set current data set. + * @brief Set current data set. */ - void setCurrentData(); + void setCurrentData(); // NOTE: inconsistent capitalization /** - * @brief AddTool add tool to list tools. + * @brief Add the given tool to the tools list. * @param id tool id. * @param tool tool. */ void AddTool(const qint64 &id, VDataTool *tool); /** - * @brief UpdateToolData update tool in list tools. - * @param id tool id. - * @param data container with variables. + * @brief Updates a given tool in the tools list. + * @param id id of the tool to update + * @param data container with variables */ void UpdateToolData(const qint64 &id, VContainer *data); /** - * @brief IncrementReferens increment reference parent objects. - * @param id parent object id. + * @brief Increment reference parent objects. RENAME: IncrementReference? + * @param id parent object id */ void IncrementReferens(qint64 id) const; /** - * @brief DecrementReferens decrement reference parent objects. - * @param id parent object id. + * @brief Decrement reference parent objects. RENAME: like above + * @param id parent object id */ void DecrementReferens(qint64 id) const; /** - * @brief TestUniqueId test exist unique id in pattern file. Each id must be unique. + * @brief Throws an exception if there exists a duplicate id in the pattern file. */ void TestUniqueId() const; /** - * @brief GetParametrLongLong return long long value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return long long value. + * @brief Returns the long long value of the given attribute. RENAME: GetParameterLongLong? + * @param domElement tag in xml tree + * @param name attribute name + * @return long long value */ qint64 GetParametrLongLong(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief GetParametrString return string value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return attribute value. + * @brief Returns the string value of the given attribute. RENAME: see above + * @param domElement tag in xml tree + * @param name attribute name + * @return attribute value */ QString GetParametrString(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief GetParametrDouble return double value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return double value. + * @brief Returns the double value of the given attribute. + * @param domElement tag in xml tree + * @param name attribute name + * @return double value */ qreal GetParametrDouble(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief SPointActiveDraw return id base point current pattern peace. - * @return id base point. + * @brief Returns the id of the base point of the current pattern piece. + * @return id of base point */ qint64 SPointActiveDraw(); - bool isPatternModified() const; - void setPatternModified(bool value); + bool isPatternModified() const; // NOTE: inconsistent capitalization + void setPatternModified(bool value); // NOTE: inconsistent capitalization QString UniqueTagText(const QString &tagName, const QString &defVal = QString()); signals: /** - * @brief ChangedActivDraw change active pattern peace. - * @param newName new pattern peace name. + * @brief The active pattern piece was changed. RENAME: ChangedActiveDraw + * @param newName new pattern piece name */ void ChangedActivDraw(const QString &newName); /** - * @brief ChangedNameDraw save new name active pattern peace. - * @param oldName old name. - * @param newName new name. + * @brief The name of the selected pattern piece was changed. + * @param oldName old name + * @param newName new name */ void ChangedNameDraw(const QString &oldName, const QString &newName); /** - * @brief FullUpdateFromFile update tool data form file. + * @brief Update tool data from file. */ void FullUpdateFromFile(); /** - * @brief patternChanged emit if we have unsaved change. + * @brief Emit if there exists an unsaved change to the pattern document. */ - void patternChanged(); + void patternChanged(); //NOTE: inconsistent capitalization /** - * @brief ShowTool highlight tool. - * @param id tool id. - * @param color highlight color. - * @param enable enable or disable highlight. + * @brief Highlight tool. + * @param id tool id + * @param color highlight color + * @param enable enable or disable highlight */ void ShowTool(qint64 id, Qt::GlobalColor color, bool enable); /** - * @brief ChangedCursor change cursor position. - * @param id tool id. + * @brief The cursor position has changed. + * @param id tool id */ void ChangedCursor(qint64 id); public slots: /** - * @brief FullUpdateTree lite parse file. + * @brief Perform a lite parse run on the pattern document. */ void FullUpdateTree(); /** - * @brief haveLiteChange we have unsaved change. + * @brief Sets that we have an unsaved change on the pattern file. Emits patternChanged(). */ - void haveLiteChange(); + void haveLiteChange(); //NOTE: inconsistent capitalization /** - * @brief ShowHistoryTool hightlight tool. - * @param id tool id. - * @param color hightlight color. - * @param enable enable or diasable hightlight. + * @brief Highlights a tool by id. + * @param id tool id + * @param color highlight color + * @param enable enable or disable highlight */ void ShowHistoryTool(qint64 id, Qt::GlobalColor color, bool enable); private: Q_DISABLE_COPY(VDomDocument) /** - * @brief map use for finding element by id. + * @brief Map used for finding element by id. */ QHash map; /** - * @brief nameActivDraw name current pattern peace. + * @brief Name of the selected pattern piece. */ QString nameActivDraw; /** - * @brief data container with data. + * @brief Container with pattern document data. */ VContainer *data; /** - * @brief tools list with pointer on tools. + * @brief Tools map with pointers to tools. */ QHash tools; /** - * @brief history history records. + * @brief Tool history record. */ QVector history; /** - * @brief cursor cursor keep id tool after which we will add new tool in file. + * @brief Cursor keep id tool after which we will add new tool in file. TODO: very unclear what does that mean? */ qint64 cursor; /** - * @brief comboBoxDraws combobox with pattern peace names. + * @brief A pointer to the QComboBox used to select pattern piece names. */ QComboBox *comboBoxDraws; /** - * @brief mode current draw mode. + * @brief Current draw mode. */ Draw::Draws *mode; /** - * @brief fileModified true if exist change in file. + * @brief True if there is an unsaved change in the document. */ bool patternModified; /** - * @brief find find element by id. - * @param node node. - * @param id id value. - * @return true if found. + * @brief Find element by id. + * @param node node + * @param id id value + * @return true if found */ bool find(const QDomElement &node, const QString& id); /** - * @brief CheckNameDraw check if exist pattern peace with this name. - * @param name pattern peace name. - * @return true if exist. + * @brief Checks whether there exists a pattern piece with the given name. + * @param name pattern piece name + * @return true if it exists */ bool CheckNameDraw(const QString& name) const; /** - * @brief SetActivDraw set current pattern peace. - * @param name pattern peace name. + * @brief Set selected pattern piece. RENAME: SetActiveDraw? SetActivePatternPiece? + * @param name pattern piece name */ void SetActivDraw(const QString& name); /** - * @brief GetActivNodeElement find element in current pattern peace by name. - * @param name name tag. - * @param element element. - * @return true if found. + * @brief Finds an element in the current pattern piece by name. RENAME: GetActiveNodeElement? + * @param name name tag + * @param element element returned by reference + * @return true if found */ bool GetActivNodeElement(const QString& name, QDomElement& element); /** - * @brief ParseDrawElement parse draw tag. - * @param sceneDraw draw scene. - * @param sceneDetail details scene. - * @param node node. - * @param parse parser file mode. + * @brief Parses a draw tag. + * @param sceneDraw draw scene + * @param sceneDetail details scene + * @param node node + * @param parse parse mode */ void ParseDrawElement(VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail, const QDomNode& node, const Document::Documents &parse); /** - * @brief ParseDrawMode parse draw tag with draw mode. - * @param sceneDraw draw scene. - * @param sceneDetail details scene. - * @param node node. - * @param parse parser file mode. - * @param mode draw mode. + * @brief Parses a draw tag in draw mode. + * @param sceneDraw draw scene + * @param sceneDetail details scene + * @param node node + * @param parse parse mode + * @param mode draw mode */ void ParseDrawMode(VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail, const QDomNode& node, const Document::Documents &parse, const Draw::Draws &mode); /** - * @brief ParseDetailElement parse detail tag. - * @param sceneDetail detail scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. + * @brief Parses a detail element tag. + * @param sceneDetail details scene + * @param domElement tag in XML tree + * @param parse parse mode */ void ParseDetailElement(VMainGraphicsScene *sceneDetail, const QDomElement &domElement, const Document::Documents &parse); /** - * @brief ParseDetails parse details tag. - * @param sceneDetail detail scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. + * @brief Parses a details tag. + * @param sceneDetail details scene + * @param domElement tag in XML tree + * @param parse parse mode */ void ParseDetails(VMainGraphicsScene *sceneDetail, const QDomElement &domElement, const Document::Documents &parse); /** - * @brief ParsePointElement parse point tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of point. - * @param mode draw mode. + * @brief Parses a point element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of point + * @param mode draw mode */ void ParsePointElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString &type); /** - * @brief ParseLineElement parse line tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param mode draw mode. + * @brief Parses a line element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param mode draw mode */ void ParseLineElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse); /** - * @brief ParseSplineElement parse spline tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. - * @param mode draw mode. + * @brief Parses a spline element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode. + * @param type type of spline + * @param mode draw mode */ void ParseSplineElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseArcElement parse arc tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. - * @param mode draw mode. + * @brief Parses an arc element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of spline + * @param mode draw mode */ void ParseArcElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseToolsElement parse tools tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. + * @brief Parses a tools element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of spline */ void ParseToolsElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseIncrementsElement parse increments tag. - * @param node tag in xml tree. + * @brief Parses an increments element tag. + * @param node tag in XML tree */ void ParseIncrementsElement(const QDomNode& node); /** - * @brief GetParametrId return value id attribute. - * @param domElement tag in xml tree. - * @return id value. + * @brief Returns the id attribute of the given element. RENAME: GetParameterId? + * @param domElement tag in XML tree + * @return id value */ qint64 GetParametrId(const QDomElement& domElement) const; /** - * @brief CollectId recursive function, try find id attribute in file. Throw exclusion if find not unique. - * @param node tag in xml tree. - * @param vector list with ids. + * @brief Recursively collects all id attribute in file. Throws an exception if a duplicate is found. + * @param node tag in XML tree + * @param vector list with ids */ void CollectId(const QDomElement &node, QVector &vector)const; };