Clean up QgsExtentGroupBox API

Make protected members private, improve documentation

Author: nyalldawson

python/gui/qgsextentgroupbox.sip

@@ -27,7 +27,6 @@ class QgsExtentGroupBox : QgsCollapsibleGroupBox
 #include "qgsextentgroupbox.h"
 %End
   public:
-    explicit QgsExtentGroupBox( QWidget *parent /TransferThis/ = 0 );
 
     enum ExtentState
     {
@@ -37,100 +36,119 @@ class QgsExtentGroupBox : QgsCollapsibleGroupBox
       ProjectLayerExtent,
     };
 
+    explicit QgsExtentGroupBox( QWidget *parent /TransferThis/ = 0 );
+%Docstring
+ Constructor for QgsExtentGroupBox.
+%End
+
     void setOriginalExtent( const QgsRectangle &originalExtent, const QgsCoordinateReferenceSystem &originalCrs );
 %Docstring
-Setup original extent - should be called as part of initialization
+ Sets the original extent and coordinate reference system for the widget. This should be called as part of initialization.
+.. seealso:: originalExtent()
+.. seealso:: originalCrs()
 %End
 
     QgsRectangle originalExtent() const;
 %Docstring
+ Returns the original extent set for the widget.
+.. seealso:: setOriginalExtent()
+.. seealso:: originalCrs()
  :rtype: QgsRectangle
 %End
-    const QgsCoordinateReferenceSystem &originalCrs() const;
+
+    QgsCoordinateReferenceSystem originalCrs() const;
 %Docstring
+ Returns the original coordinate reference system set for the widget.
+.. seealso:: originalExtent()
+.. seealso:: setOriginalExtent()
  :rtype: QgsCoordinateReferenceSystem
 %End
 
     void setCurrentExtent( const QgsRectangle &currentExtent, const QgsCoordinateReferenceSystem &currentCrs );
 %Docstring
-Setup current extent - should be called as part of initialization (or whenever current extent changes)
+ Sets the current extent to show in the widget - should be called as part of initialization (or whenever current extent changes).
+.. seealso:: currentExtent()
+.. seealso:: currentCrs()
 %End
 
     QgsRectangle currentExtent() const;
 %Docstring
+ Returns the current extent set for the widget.
+.. seealso:: setCurrentExtent()
+.. seealso:: currentCrs()
  :rtype: QgsRectangle
 %End
-    const QgsCoordinateReferenceSystem &currentCrs() const;
+
+    QgsCoordinateReferenceSystem currentCrs() const;
 %Docstring
+ Returns the coordinate reference system for the current extent set for the widget.
+.. seealso:: setCurrentExtent()
+.. seealso:: currentExtent()
  :rtype: QgsCoordinateReferenceSystem
 %End
 
     void setOutputCrs( const QgsCoordinateReferenceSystem &outputCrs );
 %Docstring
-Should be called as part of initialization and whenever the the output CRS is changed
+ Sets the output CRS - may need to be used for transformation from original/current extent.
+ Should be called as part of initialization and whenever the the output CRS is changed.
 %End
 
     QgsRectangle outputExtent() const;
 %Docstring
-Get the resulting extent - in output CRS coordinates
+ Returns the extent shown in the widget - in output CRS coordinates.
  :rtype: QgsRectangle
 %End
 
     QgsExtentGroupBox::ExtentState extentState() const;
 %Docstring
+ Returns the currently selected state for the widget's extent.
  :rtype: QgsExtentGroupBox.ExtentState
 %End
 
     void setTitleBase( const QString &title );
 %Docstring
+ Sets the base part of ``title`` of the group box (will be appended with extent state)
 .. versionadded:: 2.12
+.. seealso:: titleBase()
 %End
+
     QString titleBase() const;
 %Docstring
+ Returns the base part of title of the group box (will be appended with extent state).
 .. versionadded:: 2.12
+.. seealso:: setTitleBase()
  :rtype: str
 %End
 
   public slots:
+
     void setOutputExtentFromOriginal();
 %Docstring
-set output extent to be the same as original extent (may be transformed to output CRS)
+ Sets the output extent to be the same as original extent (may be transformed to output CRS).
 %End
 
     void setOutputExtentFromCurrent();
 %Docstring
-set output extent to be the same as current extent (may be transformed to output CRS)
+ Sets the output extent to be the same as current extent (may be transformed to output CRS).
 %End
 
     void setOutputExtentFromUser( const QgsRectangle &extent, const QgsCoordinateReferenceSystem &crs );
 %Docstring
-set output extent to custom extent (may be transformed to output CRS)
+ Sets the output extent to a custom extent (may be transformed to output CRS).
 %End
 
-  signals:
-    void extentChanged( const QgsRectangle &r );
+    void setOutputExtentFromLayer( const QgsMapLayer *layer );
 %Docstring
-emitted when extent is changed
+ Sets the output extent to match a ``layer``'s extent (may be transformed to output CRS).
+.. versionadded:: 3.0
 %End
 
-  protected slots:
-
-    void on_mXMinLineEdit_textEdited( const QString & );
-    void on_mXMaxLineEdit_textEdited( const QString & );
-    void on_mYMinLineEdit_textEdited( const QString & );
-    void on_mYMaxLineEdit_textEdited( const QString & );
-
-    void groupBoxClicked();
-
-  protected:
-    void setOutputExtent( const QgsRectangle &r, const QgsCoordinateReferenceSystem &srcCrs, QgsExtentGroupBox::ExtentState state );
-    void setOutputExtentFromLineEdit();
-    void updateTitle();
-
-
-
-
+  signals:
 
+    void extentChanged( const QgsRectangle &r );
+%Docstring
+ Emitted when the widget's extent is changed.
+%End
 
 };
 

src/gui/qgsextentgroupbox.cpp

@@ -171,10 +171,7 @@ void QgsExtentGroupBox::setExtentToLayerExtent( const QString &layerId )
   if ( !layer )
     return;
 
-  mExtentLayerId = layerId;
-  mExtentLayerName = layer->name();
-
-  setOutputExtent( layer->extent(), layer->crs(), ProjectLayerExtent );
+  setOutputExtentFromLayer( layer );
 }
 
 void QgsExtentGroupBox::setOutputExtentFromCurrent()
@@ -193,6 +190,17 @@ void QgsExtentGroupBox::setOutputExtentFromUser( const QgsRectangle &extent, con
   setOutputExtent( extent, crs, UserExtent );
 }
 
+void QgsExtentGroupBox::setOutputExtentFromLayer( const QgsMapLayer *layer )
+{
+  if ( !layer )
+    return;
+
+  mExtentLayerId = layer->id();
+  mExtentLayerName = layer->name();
+
+  setOutputExtent( layer->extent(), layer->crs(), ProjectLayerExtent );
+}
+
 void QgsExtentGroupBox::groupBoxClicked()
 {
   if ( !isCheckable() )

src/gui/qgsextentgroupbox.h

@@ -26,6 +26,7 @@
 
 class QgsCoordinateReferenceSystem;
 class QgsMapLayerModel;
+class QgsMapLayer;
 
 /** \ingroup gui
  * Collapsible group box for configuration of extent, typically for a save operation.
@@ -43,8 +44,8 @@ class GUI_EXPORT QgsExtentGroupBox : public QgsCollapsibleGroupBox, private Ui::
     Q_PROPERTY( QString titleBase READ titleBase WRITE setTitleBase )
 
   public:
-    explicit QgsExtentGroupBox( QWidget *parent SIP_TRANSFERTHIS = 0 );
 
+    //! Available states for the current extent selection in the widget
     enum ExtentState
     {
       OriginalExtent,  //!< Layer's extent
@@ -53,58 +54,124 @@ class GUI_EXPORT QgsExtentGroupBox : public QgsCollapsibleGroupBox, private Ui::
       ProjectLayerExtent, //!< Extent taken from a layer within the project
     };
 
-    //! Setup original extent - should be called as part of initialization
+    /**
+     * Constructor for QgsExtentGroupBox.
+     */
+    explicit QgsExtentGroupBox( QWidget *parent SIP_TRANSFERTHIS = 0 );
+
+    /**
+     * Sets the original extent and coordinate reference system for the widget. This should be called as part of initialization.
+     * \see originalExtent()
+     * \see originalCrs()
+     */
     void setOriginalExtent( const QgsRectangle &originalExtent, const QgsCoordinateReferenceSystem &originalCrs );
 
+    /**
+     * Returns the original extent set for the widget.
+     * \see setOriginalExtent()
+     * \see originalCrs()
+     */
     QgsRectangle originalExtent() const { return mOriginalExtent; }
-    const QgsCoordinateReferenceSystem &originalCrs() const { return mOriginalCrs; }
 
-    //! Setup current extent - should be called as part of initialization (or whenever current extent changes)
+    /**
+     * Returns the original coordinate reference system set for the widget.
+     * \see originalExtent()
+     * \see setOriginalExtent()
+     */
+    QgsCoordinateReferenceSystem originalCrs() const { return mOriginalCrs; }
+
+    /**
+     * Sets the current extent to show in the widget - should be called as part of initialization (or whenever current extent changes).
+     * \see currentExtent()
+     * \see currentCrs()
+     */
     void setCurrentExtent( const QgsRectangle &currentExtent, const QgsCoordinateReferenceSystem &currentCrs );
 
+    /**
+     * Returns the current extent set for the widget.
+     * \see setCurrentExtent()
+     * \see currentCrs()
+     */
     QgsRectangle currentExtent() const { return mCurrentExtent; }
-    const QgsCoordinateReferenceSystem &currentCrs() const { return mCurrentCrs; }
 
-    //! Set the output CRS - may need to be used for transformation from original/current extent.
-    //! Should be called as part of initialization and whenever the the output CRS is changed
+    /**
+     * Returns the coordinate reference system for the current extent set for the widget.
+     * \see setCurrentExtent()
+     * \see currentExtent()
+     */
+    QgsCoordinateReferenceSystem currentCrs() const { return mCurrentCrs; }
+
+    /**
+     * Sets the output CRS - may need to be used for transformation from original/current extent.
+     * Should be called as part of initialization and whenever the the output CRS is changed.
+     */
     void setOutputCrs( const QgsCoordinateReferenceSystem &outputCrs );
 
-    //! Get the resulting extent - in output CRS coordinates
+    /**
+     * Returns the extent shown in the widget - in output CRS coordinates.
+     */
     QgsRectangle outputExtent() const;
 
+    /**
+     * Returns the currently selected state for the widget's extent.
+     */
     QgsExtentGroupBox::ExtentState extentState() const { return mExtentState; }
 
-    //! Set base part of title of the group box (will be appended with extent state)
-    //! \since QGIS 2.12
+    /**
+     * Sets the base part of \a title of the group box (will be appended with extent state)
+     * \since QGIS 2.12
+     * \see titleBase()
+     */
     void setTitleBase( const QString &title );
-    //! Set base part of title of the group box (will be appended with extent state)
-    //! \since QGIS 2.12
+
+    /**
+     * Returns the base part of title of the group box (will be appended with extent state).
+     * \since QGIS 2.12
+     * \see setTitleBase()
+     */
     QString titleBase() const;
 
   public slots:
-    //! set output extent to be the same as original extent (may be transformed to output CRS)
+
+    /**
+     * Sets the output extent to be the same as original extent (may be transformed to output CRS).
+     */
     void setOutputExtentFromOriginal();
 
-    //! set output extent to be the same as current extent (may be transformed to output CRS)
+    /**
+     * Sets the output extent to be the same as current extent (may be transformed to output CRS).
+     */
     void setOutputExtentFromCurrent();
 
-    //! set output extent to custom extent (may be transformed to output CRS)
+    /**
+     * Sets the output extent to a custom extent (may be transformed to output CRS).
+     */
     void setOutputExtentFromUser( const QgsRectangle &extent, const QgsCoordinateReferenceSystem &crs );
 
+    /**
+     * Sets the output extent to match a \a layer's extent (may be transformed to output CRS).
+     * \since QGIS 3.0
+     */
+    void setOutputExtentFromLayer( const QgsMapLayer *layer );
+
   signals:
-    //! emitted when extent is changed
+
+    /**
+     * Emitted when the widget's extent is changed.
+     */
     void extentChanged( const QgsRectangle &r );
 
-  protected slots:
+  private slots:
 
     void on_mXMinLineEdit_textEdited( const QString & ) { setOutputExtentFromLineEdit(); }
     void on_mXMaxLineEdit_textEdited( const QString & ) { setOutputExtentFromLineEdit(); }
     void on_mYMinLineEdit_textEdited( const QString & ) { setOutputExtentFromLineEdit(); }
     void on_mYMaxLineEdit_textEdited( const QString & ) { setOutputExtentFromLineEdit(); }
 
     void groupBoxClicked();
+    void layerMenuAboutToShow();
 
-  protected:
+  private:
     void setOutputExtent( const QgsRectangle &r, const QgsCoordinateReferenceSystem &srcCrs, QgsExtentGroupBox::ExtentState state );
     void setOutputExtentFromLineEdit();
     void updateTitle();
@@ -122,12 +189,6 @@ class GUI_EXPORT QgsExtentGroupBox : public QgsCollapsibleGroupBox, private Ui::
     QgsRectangle mOriginalExtent;
     QgsCoordinateReferenceSystem mOriginalCrs;
 
-  private slots:
-
-    void layerMenuAboutToShow();
-
-  private:
-
     QMenu *mLayerMenu = nullptr;
     QgsMapLayerModel *mMapLayerModel = nullptr;
     QList< QAction * > mMenuActions;