Add some doxymentation to collapsible group boxes

qgis · Jun 2, 2015 · ddfb9d1 · ddfb9d1
1 parent 4157b33
commit ddfb9d1
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 20 deletions.
diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
@@ -474,7 +474,7 @@ class CORE_EXPORT QgsGeometry
      */
     QString exportToGeoJSON( const int &precision = 17 ) const;
 
-    /** try to convert the geometry to the requested type
+    /** Try to convert the geometry to the requested type
      * @param destType the geometry type to be converted to
      * @param destMultipart determines if the output geometry will be multipart or not
      * @return the converted geometry or NULL pointer if the conversion fails.
@@ -484,31 +484,31 @@ class CORE_EXPORT QgsGeometry
 
     /* Accessor functions for getting geometry data */
 
-    /** return contents of the geometry as a point
+    /** Return contents of the geometry as a point
         if wkbType is WKBPoint, otherwise returns [0,0] */
     QgsPoint asPoint() const;
 
-    /** return contents of the geometry as a polyline
+    /** Return contents of the geometry as a polyline
         if wkbType is WKBLineString, otherwise an empty list */
     QgsPolyline asPolyline() const;
 
-    /** return contents of the geometry as a polygon
+    /** Return contents of the geometry as a polygon
         if wkbType is WKBPolygon, otherwise an empty list */
     QgsPolygon asPolygon() const;
 
-    /** return contents of the geometry as a multi point
+    /** Return contents of the geometry as a multi point
         if wkbType is WKBMultiPoint, otherwise an empty list */
     QgsMultiPoint asMultiPoint() const;
 
-    /** return contents of the geometry as a multi linestring
+    /** Return contents of the geometry as a multi linestring
         if wkbType is WKBMultiLineString, otherwise an empty list */
     QgsMultiPolyline asMultiPolyline() const;
 
-    /** return contents of the geometry as a multi polygon
+    /** Return contents of the geometry as a multi polygon
         if wkbType is WKBMultiPolygon, otherwise an empty list */
     QgsMultiPolygon asMultiPolygon() const;
 
-    /** return contents of the geometry as a list of geometries
+    /** Return contents of the geometry as a list of geometries
      @note added in version 1.1 */
     QList<QgsGeometry*> asGeometryCollection() const;
 
@@ -536,9 +536,14 @@ class CORE_EXPORT QgsGeometry
       @note added in version 1.2 */
     bool deletePart( int partNum );
 
-    /**Converts single type geometry into multitype geometry
-     e.g. a polygon into a multipolygon geometry with one polygon
-    @return true in case of success and false else*/
+    /**
+     * Converts single type geometry into multitype geometry
+     * e.g. a polygon into a multipolygon geometry with one polygon
+     * If it is already a multipart geometry, it will return true and
+     * not change the geometry.
+     *
+     * @return true in case of success and false else
+     */
     bool convertToMultiType();
 
     /** Modifies geometry to avoid intersections with the layers specified in project properties

diff --git a/src/gui/qgscollapsiblegroupbox.cpp b/src/gui/qgscollapsiblegroupbox.cpp
@@ -601,7 +601,7 @@ void QgsCollapsibleGroupBox::loadState()
   setUpdatesEnabled( true );
 }
 
-void QgsCollapsibleGroupBox::saveState()
+void QgsCollapsibleGroupBox::saveState() const
 {
   //QgsDebugMsg( "Entered" );
   if ( !mSettings )

diff --git a/src/gui/qgscollapsiblegroupbox.h b/src/gui/qgscollapsiblegroupbox.h
@@ -65,32 +65,61 @@ class GUI_EXPORT QgsGroupBoxCollapseButton : public QToolButton
  * Holding Alt modifier key when toggling collapsed state will synchronize the toggling across other collapsible group boxes with the same syncGroup QString value
  * Holding Shift modifier key when attempting to toggle collapsed state will expand current group box, then collapse any others with the same syncGroup QString value
  * @note To add Collapsible properties in promoted QtDesigner widgets, you can add the following "Dynamic properties" by clicking on the green + in the propreties palette:
- * bool collapsed, QString syncGroup
+ * bool collapsed, QString syncGroup, bool scrollOnExpand
  */
 
 class GUI_EXPORT QgsCollapsibleGroupBoxBasic : public QGroupBox
 {
     Q_OBJECT
 
+    /**
+     * The collapsed state of this group box. If it is set to true, all content is hidden
+     * if it is set to false all content is shown.
+     */
     Q_PROPERTY( bool collapsed READ isCollapsed WRITE setCollapsed USER true )
+
+    /**
+     * An optional group to be collapsed and uncollapsed in sync with this group box if the Alt-modifier
+     * is pressed while collapsing / uncollapsing.
+     */
     Q_PROPERTY( QString syncGroup READ syncGroup WRITE setSyncGroup )
+
+    /**
+     * If this property is set to true, a parent scroll area will try to make sure that the whole
+     * group box is visible when uncollapsing it.
+     */
     Q_PROPERTY( bool scrollOnExpand READ scrollOnExpand WRITE setScrollOnExpand )
 
   public:
     QgsCollapsibleGroupBoxBasic( QWidget *parent = 0 );
     QgsCollapsibleGroupBoxBasic( const QString &title, QWidget *parent = 0 );
     ~QgsCollapsibleGroupBoxBasic();
 
+    /**
+     * Returns the current collapsed state of this group box
+     */
     bool isCollapsed() const { return mCollapsed; }
+    /**
+     * Collapse or uncollapse this groupbox
+     *
+     * @param collapse Will collapse on true and uncollapse on false
+     */
     void setCollapsed( bool collapse );
 
-    /** Named group which synchronizes collapsing action when triangle is clicked while holding alt modifier key */
+    /**
+     * Named group which synchronizes collapsing action when triangle is clicked while holding alt modifier key
+     */
     QString syncGroup() const { return mSyncGroup; }
+
+    /**
+     * Named group which synchronizes collapsing action when triangle is clicked while holding alt modifier key
+     */
     void setSyncGroup( QString grp );
 
-    //! set this to false to not automatically scroll parent QScrollArea to this widget's contents when expanded
+    //! Set this to false to not automatically scroll parent QScrollArea to this widget's contents when expanded
     void setScrollOnExpand( bool scroll ) { mScrollOnExpand = scroll; }
 
+    //! If this is set to false the parent QScrollArea will not be automatically scrolled to this widget's contents when expanded
     bool scrollOnExpand() {return mScrollOnExpand;}
 
   signals:
@@ -149,11 +178,15 @@ class GUI_EXPORT QgsCollapsibleGroupBox : public QgsCollapsibleGroupBoxBasic
 {
     Q_OBJECT
 
-    Q_PROPERTY( bool collapsed READ isCollapsed WRITE setCollapsed USER true )
+    /**
+     * Shall the collapsed state of this group box be saved and loaded persistently in QSettings
+     */
     Q_PROPERTY( bool saveCollapsedState READ saveCollapsedState WRITE setSaveCollapsedState )
+
+    /**
+     * Shall the checked state of this group box be saved and loaded persistently in QSettings
+     */
     Q_PROPERTY( bool saveCheckedState READ saveCheckedState WRITE setSaveCheckedState )
-    Q_PROPERTY( QString syncGroup READ syncGroup WRITE setSyncGroup )
-    Q_PROPERTY( bool scrollOnExpand READ scrollOnExpand WRITE setScrollOnExpand )
 
   public:
     QgsCollapsibleGroupBox( QWidget *parent = 0, QSettings* settings = 0 );
@@ -172,13 +205,28 @@ class GUI_EXPORT QgsCollapsibleGroupBox : public QgsCollapsibleGroupBoxBasic
     bool saveCollapsedState() { return mSaveCollapsedState; }
     bool saveCheckedState() { return mSaveCheckedState; }
 
-    //! set this to a defined string to share save/restore states across different parent dialogs
+    //! Set this to a defined string to share save/restore states across different parent dialogs
     void setSettingGroup( const QString &group ) { mSettingGroup = group; }
+    //! Returns the name of the setting group in which the collapsed state will be saved
     QString settingGroup() const { return mSettingGroup; }
 
   protected slots:
+    /**
+     * Will load the collapsed and checked state
+     *
+     * The configuration path from which it is loaded is defined by
+     *  * The object name
+     *  * The settingGroup
+     */
     void loadState();
-    void saveState();
+    /**
+     * Will save the collapsed and checked state
+     *
+     * The configuration path to which it is saved is defined by
+     *  * The object name
+     *  * The settingGroup
+     */
+    void saveState() const;
 
   protected:
     void init();