From e938673872eef8360b7222da101dbdee4e5d0301 Mon Sep 17 00:00:00 2001 From: Simon De Backer Date: Sun, 2 Aug 2020 15:09:21 +0200 Subject: [PATCH] Add documentation --- sources/diagram.cpp | 26 ++++++++++++++--------- sources/genericpanel.cpp | 45 ++++++++++++++++++++++++++-------------- sources/genericpanel.h | 7 ++++--- 3 files changed, 49 insertions(+), 29 deletions(-) diff --git a/sources/diagram.cpp b/sources/diagram.cpp index e9cb164a5..89832d4a5 100644 --- a/sources/diagram.cpp +++ b/sources/diagram.cpp @@ -54,10 +54,10 @@ const qreal Diagram::margin = 5.0; QColor Diagram::background_color = Qt::white; /** - * @brief Diagram::Diagram - * Constructor - * @param project : The project of this diagram and also parent QObject - */ + @brief Diagram::Diagram + Constructor + @param project : The project of this diagram and also parent QObject +*/ Diagram::Diagram(QETProject *project) : QGraphicsScene (project), m_project (project), @@ -71,11 +71,13 @@ Diagram::Diagram(QETProject *project) : m_freeze_new_conductors_ (false) { setItemIndexMethod(QGraphicsScene::NoIndex); - //Set to no index, because they can be the source of the crash with conductor and shape ghost. - //https://forum.qt.io/topic/71316/qgraphicsscenefinditembsptreevisitor-visit-crashes-due-to-an-obsolete-paintevent-after-qgraphicsscene-removeitem - //https://stackoverflow.com/questions/38458830/crash-after-qgraphicssceneremoveitem-with-custom-item-class - //http://www.qtcentre.org/archive/index.php/t-33730.html - //http://tech-artists.org/t/qt-properly-removing-qgraphicitems/3063 + /* Set to no index, + * because they can be the source of the crash with conductor and shape ghost. + * https://forum.qt.io/topic/71316/qgraphicsscenefinditembsptreevisitor-visit-crashes-due-to-an-obsolete-paintevent-after-qgraphicsscene-removeitem + * https://stackoverflow.com/questions/38458830/crash-after-qgraphicssceneremoveitem-with-custom-item-class + * http://www.qtcentre.org/archive/index.php/t-33730.html + * http://tech-artists.org/t/qt-properly-removing-qgraphicitems/3063 + */ qgi_manager_ = new QGIManager(this); setBackgroundBrush(Qt::white); @@ -1269,7 +1271,11 @@ void Diagram::removeItem(QGraphicsItem *item) QGraphicsScene::removeItem(item); } - +/** + @brief Diagram::titleChanged + emit(diagramTitleChanged(this, title)); + @param title +*/ void Diagram::titleChanged(const QString &title) { emit(diagramTitleChanged(this, title)); } diff --git a/sources/genericpanel.cpp b/sources/genericpanel.cpp index bac904284..3aabfe973 100644 --- a/sources/genericpanel.cpp +++ b/sources/genericpanel.cpp @@ -167,7 +167,7 @@ QTreeWidgetItem *GenericPanel::getItemForProject(QETProject *project, bool *crea @brief GenericPanel::updateProjectItem @param project_qtwi @param project - @param options + @param options (unused) @param freshly_created @return updateItem(project_qtwi, options, freshly_created) */ @@ -264,7 +264,7 @@ QTreeWidgetItem *GenericPanel::fillProjectItem(QTreeWidgetItem *project_qtwi, QE @brief GenericPanel::addDiagram @param diagram @param parent_item - @param options + @param options (unused) @return diagram_qtwi */ QTreeWidgetItem *GenericPanel::addDiagram(Diagram *diagram, QTreeWidgetItem *parent_item, PanelOptions options) { @@ -369,7 +369,7 @@ QTreeWidgetItem *GenericPanel::updateDiagramItem(QTreeWidgetItem *diagram_qtwi, /** @brief GenericPanel::fillDiagramItem @param diagram_qtwi - @param Q_UNUSED(diagram) + @param diagram (unused) @param options @param freshly_created @return fillItem(diagram_qtwi, options, freshly_created) @@ -566,7 +566,7 @@ QTreeWidgetItem *GenericPanel::updateTemplateItem(QTreeWidgetItem *tb_template_q /** @brief GenericPanel::fillTemplateItem @param tb_template_qtwi - @param tb_template + @param tb_template (unused) @param options @param freshly_created @return fillItem(tb_template_qtwi, options, freshly_created) @@ -578,12 +578,12 @@ QTreeWidgetItem *GenericPanel::fillTemplateItem(QTreeWidgetItem *tb_template_qtw /** @brief GenericPanel::updateItem - This generic method is called at the end of each update*Item method. Its - only purpose is being reimplemented in a subclass. The default - implementation does nothing. + This generic method is called at the end of each update*Item method. + Its only purpose is being reimplemented in a subclass. + The default implementation does nothing. @param qtwi - @param options - @param freshly_created + @param options (unused) + @param freshly_created (unused) @return qtwi */ QTreeWidgetItem *GenericPanel::updateItem(QTreeWidgetItem *qtwi, PanelOptions options, bool freshly_created) { @@ -621,7 +621,7 @@ void GenericPanel::projectInformationsChanged(QETProject *project) { /** @brief GenericPanel::diagramAdded @param project - @param diagram + @param diagram (unused) */ void GenericPanel::diagramAdded(QETProject *project, Diagram *diagram) { Q_UNUSED(diagram) @@ -632,7 +632,7 @@ void GenericPanel::diagramAdded(QETProject *project, Diagram *diagram) { /** @brief GenericPanel::diagramRemoved @param project - @param diagram + @param diagram (unused) */ void GenericPanel::diagramRemoved(QETProject *project, Diagram *diagram) { Q_UNUSED(diagram) @@ -679,7 +679,10 @@ void GenericPanel::projectDiagramsOrderChanged(QETProject *project, int from, in } /** + @brief GenericPanel::diagramTitleChanged Inform this panel the diagram \a diagram has changed its title to \a title. + @param diagram + @param title (unused) */ void GenericPanel::diagramTitleChanged(Diagram *diagram, const QString &title) { Q_UNUSED(title) @@ -688,8 +691,10 @@ void GenericPanel::diagramTitleChanged(Diagram *diagram, const QString &title) { } /** - @param collection Title block templates collection that changed and should be updated - @param template_name Name of the changed template (unused) + @brief GenericPanel::templatesCollectionChanged + @param collection : + Title block templates collection that changed and should be updated + @param template_name : Name of the changed template (unused) */ void GenericPanel::templatesCollectionChanged(TitleBlockTemplatesCollection*collection, const QString &template_name) { Q_UNUSED(template_name) @@ -700,7 +705,7 @@ void GenericPanel::templatesCollectionChanged(TitleBlockTemplatesCollection*coll /** @brief GenericPanel::diagramUsedTemplate @param collection - @param name + @param name : (unused) */ void GenericPanel::diagramUsedTemplate(TitleBlockTemplatesCollection *collection, const QString &name) { Q_UNUSED(name) @@ -731,6 +736,7 @@ QString GenericPanel::defaultText(QET::ItemType type) { } /** + @brief GenericPanel::defaultIcon @param type Item type we want the default icon for @return the default icon for \a type */ @@ -763,10 +769,11 @@ QTreeWidgetItem *GenericPanel::makeItem(QET::ItemType type, QTreeWidgetItem *par } /** + @brief GenericPanel::deleteItem Delete and item and its children. @param item item to delete @param deleted_on_cascade true if the item is not being directly deleted - but is undergoing the deletion of its parent. + but is undergoing the deletion of its parent. (unused) */ void GenericPanel::deleteItem(QTreeWidgetItem *item, bool deleted_on_cascade) { Q_UNUSED(deleted_on_cascade) @@ -781,6 +788,7 @@ void GenericPanel::deleteItem(QTreeWidgetItem *item, bool deleted_on_cascade) { } /** + @brief GenericPanel::markItemAsUnused Mark the provided QTreeWidgetItem as unused in its parent project. @param qtwi A QTreeWidgetItem */ @@ -804,10 +812,11 @@ void GenericPanel::reparent(QTreeWidgetItem *item, QTreeWidgetItem *parent) { } /** - @return the child items of \a item of type \a type + @brief GenericPanel::childItems @param item Parent item that will be searched. @param type Type of items to look for. @param recursive Whether to search recursively. + @return the child items of \a item of type \a type */ QList GenericPanel::childItems(QTreeWidgetItem *item, QET::ItemType type, bool recursive) const { QList items; @@ -879,8 +888,11 @@ void GenericPanel::unregisterItem(QTreeWidgetItem *item) { } /** + @brief GenericPanel::event Handle various events; reimplemented here to emit the signal firstActivated(). + @param event + @return */ bool GenericPanel::event(QEvent *event) { if (first_activation_) { @@ -893,6 +905,7 @@ bool GenericPanel::event(QEvent *event) { } /** + @brief GenericPanel::emitFirstActivated Emit the signal firstActivated(). */ void GenericPanel::emitFirstActivated() { diff --git a/sources/genericpanel.h b/sources/genericpanel.h index b70217f5e..662be772e 100644 --- a/sources/genericpanel.h +++ b/sources/genericpanel.h @@ -27,10 +27,11 @@ class TitleBlockTemplatesCollection; class TitleBlockTemplateLocation; /** + @brief The GenericPanel class The generic panel is a QTreeWidget subclass providing extra methods - allowing developers to easily add objects (projects, diagrams, title block - templates, elements, ...) to it; it also ensures the displayed information - remains up to date. + allowing developers to easily add objects + (projects, diagrams, title block templates, elements, ...) to it; + it also ensures the displayed information remains up to date. */ class GenericPanel : public QTreeWidget { Q_OBJECT