[FEATURE] Plugins can add pages to vector layer properties*

* This is actually a followup to 87121d, which fixes leaks & clarifies some docs. But I figured the ability to add custom pages to the properties is worth highlighting as a feature on it's own, or it may go unnoticed in the other globe related changes!
qgis · May 30, 2016 · 71f8e3e · 71f8e3e
1 parent 2069c27
commit 71f8e3e
Show file tree

Hide file tree

Showing 17 changed files with 131 additions and 48 deletions.
diff --git a/python/core/qgsbillboardregistry.sip b/python/core/qgsbillboardregistry.sip
@@ -1,22 +1,31 @@
-/** Billboard items stored in the QgsBillBoardRegistry */
+/** \ingroup core
+ * \class QgsBillBoardItem
+ * \note added in QGIS 2.16
+ * A billboard item stored in the QgsBillBoardRegistry.
+ */
 class QgsBillBoardItem
 {
 %TypeHeaderCode
 #include <qgsbillboardregistry.h>
 %End
   public:
-    QImage image; /* The image of the billboard */
-    QgsPoint worldPos; /* The WGS84 world position of the billboard */
-    QString layerId; /* The layer which the image is part of, if any */
+    //! The image of the billboard
+    QImage image;
+    //! The WGS84 world position of the billboard
+    QgsPoint worldPos;
+    //! The layer which the image is part of, if any
+    QString layerId;
 };
 
-/**
+/** \ingroup core
+ * \class QgsBillBoardRegistry
+ * \note added in QGIS 2.16
  * @brief The QgsBillBoardRegistry class stores images which should
  * be displayed as billboards in the globe plugin.
  * Map canvas items and layers may decide to add items which should
  * be drawn as billboards in the globe.
  *
- * Retreive the instance pointer to a QgsBillBoardRegistry for a
+ * Retrieve the instance pointer to a QgsBillBoardRegistry for a
  * project via QgsProject::instance()->billboardRegistry().
  */
 class QgsBillBoardRegistry : public QObject
@@ -25,14 +34,20 @@ class QgsBillBoardRegistry : public QObject
 #include <qgsbillboardregistry.h>
 %End
   public:
+
+    ~QgsBillBoardRegistry();
+
     /**
-     * @brief Adds a billboard to the registry
-     * @param parent The parent (i.e. a QgsMapLayer or a QgsMapCanvasItem) which is creating the billboard
+     * @brief Adds a billboard to the registry.
+     * @param parent The parent (i.e. a QgsMapLayer or a QgsMapCanvasItem) which is creating the billboard.
+     * Each parent can only have a single billboard - if a billboard for the parent already exists, it will
+     * be updated to match to new image and settings.
      * @param image The billboard image
      * @param worldPos The geo position of the image, in WGS84
      * @param layerId The id of the layer to which the item belongs, if any
      */
     void addItem( void* parent, const QImage& image, const QgsPoint& worldPos, const QString& layerId = QString() );
+
     /**
      * @brief Removes all billboards which were created by the specified parent
      * @param parent The parent

diff --git a/python/core/qgsmapsettings.sip b/python/core/qgsmapsettings.sip
@@ -66,9 +66,18 @@ class QgsMapSettings
     //! @note added in 2.8
     void setLayerStyleOverrides( const QMap<QString, QString>& overrides );
 
-    //! Get custom rendering flags, separated by ';'. Layers might honour these to alter their rendering.
-    const QString& customRenderFlags() const;
-    //! Set custom rendering flags, separated by ';'. Layers might honour these to alter their rendering.
+    /** Get custom rendering flags. Layers might honour these to alter their rendering.
+     *  @returns custom flags strings, separated by ';'
+     * @note added in QGIS 2.16
+     * @see setCustomRenderFlags()
+     */
+    QString customRenderFlags() const;
+
+    /** Sets the custom rendering flags. Layers might honour these to alter their rendering.
+     * @param customRenderFlags custom flags strings, separated by ';'
+     * @note added in QGIS 2.16
+     * @see customRenderFlags()
+     */
     void setCustomRenderFlags( const QString& customRenderFlags );
 
     //! sets whether to use projections for this layer set

diff --git a/python/gui/qgisinterface.sip b/python/gui/qgisinterface.sip
@@ -279,10 +279,16 @@ class QgisInterface : QObject
     /** Unregister a previously registered action. (e.g. when plugin is going to be unloaded) */
     virtual bool unregisterMainWindowAction( QAction* action ) = 0;
 
-    /** Register a new tab in the vector layer properties dialog */
+    /** Register a new tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see unregisterMapLayerPropertiesFactory()
+    */
     virtual void registerMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) = 0;
 
-    /** Unregister a previously registered tab in the layer properties dialog */
+    /** Unregister a previously registered tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see registerMapLayerPropertiesFactory()
+    */
     virtual void unregisterMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) = 0;
 
     // @todo is this deprecated in favour of QgsContextHelp?

diff --git a/python/gui/qgsmaplayerpropertiesfactory.sip b/python/gui/qgsmaplayerpropertiesfactory.sip
@@ -1,5 +1,7 @@
 /** \ingroup gui
- * \note added in 2.1
+ * \class QgsMapLayerPropertiesFactory
+ * \note added in QGIS 2.16
+ * Factory class for creating custom map layer property pages
  */
 class QgsMapLayerPropertiesFactory
 {
@@ -28,5 +30,5 @@ class QgsMapLayerPropertiesFactory
      * @param view The parent QListView
      * @return The QListWidgetItem for the properties page
      */
-    virtual QListWidgetItem* createVectorLayerPropertiesItem( QgsVectorLayer* layer, QListWidget* view ) = 0;
+    virtual QListWidgetItem* createVectorLayerPropertiesItem( QgsVectorLayer* layer, QListWidget* view ) = 0 /Factory/;
 };
diff --git a/python/gui/qgsvectorlayerpropertiespage.sip b/python/gui/qgsvectorlayerpropertiespage.sip
@@ -1,9 +1,7 @@
 /** \ingroup gui
- * \note added in 2.1
- */
-
-/**
- * @brief Base class for custom vector layer property pages
+ * \class QgsVectorLayerPropertiesPage
+ * \note added in QGIS 2.16
+ * Base class for custom vector layer property pages
  */
 class QgsVectorLayerPropertiesPage : QWidget
 {
@@ -12,8 +10,11 @@ class QgsVectorLayerPropertiesPage : QWidget
 %End
 
   public:
-    /** Constructor */
-    explicit QgsVectorLayerPropertiesPage( QWidget *parent = 0 );
+
+    /** Constructor for QgsVectorLayerPropertiesPage.
+     * @param parent parent widget
+    */
+    explicit QgsVectorLayerPropertiesPage( QWidget *parent /TransferThis/ = 0 );
 
   public slots:
     /** Apply changes */

diff --git a/src/app/qgisapp.cpp b/src/app/qgisapp.cpp
@@ -11031,7 +11031,7 @@ void QgisApp::showLayerProperties( QgsMapLayer *ml )
 #else
     QgsVectorLayerProperties *vlp = new QgsVectorLayerProperties( vlayer, this );
 #endif
-    foreach ( QgsMapLayerPropertiesFactory* factory, mMapLayerPropertiesFactories )
+    Q_FOREACH ( QgsMapLayerPropertiesFactory* factory, mMapLayerPropertiesFactories )
     {
       vlp->addPropertiesPageFactory( factory );
     }

diff --git a/src/app/qgisappinterface.h b/src/app/qgisappinterface.h
@@ -288,10 +288,16 @@ class APP_EXPORT QgisAppInterface : public QgisInterface
     /** Unregister a previously registered action. (e.g. when plugin is going to be unloaded. */
     virtual bool unregisterMainWindowAction( QAction* action ) override;
 
-    /** Register a new tab in the layer properties dialog */
+    /** Register a new tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see unregisterMapLayerPropertiesFactory()
+    */
     virtual void registerMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) override;
 
-    /** Unregister a previously registered tab in the layer properties dialog */
+    /** Unregister a previously registered tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see registerMapLayerPropertiesFactory()
+    */
     virtual void unregisterMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) override;
 
     /** Accessors for inserting items into menus and toolbars.

diff --git a/src/app/qgsvectorlayerproperties.cpp b/src/app/qgsvectorlayerproperties.cpp
@@ -622,7 +622,7 @@ void QgsVectorLayerProperties::apply()
   diagramPropertiesDialog->apply();
 
   // apply all plugin dialogs
-  foreach ( QgsVectorLayerPropertiesPage* page, mLayerPropertiesPages )
+  Q_FOREACH ( QgsVectorLayerPropertiesPage* page, mLayerPropertiesPages )
   {
     page->apply();
   }

diff --git a/src/core/qgsbillboardregistry.cpp b/src/core/qgsbillboardregistry.cpp
@@ -17,6 +17,11 @@
 
 #include "qgsbillboardregistry.h"
 
+QgsBillBoardRegistry::~QgsBillBoardRegistry()
+{
+  qDeleteAll( mItems );
+}
+
 void QgsBillBoardRegistry::addItem( void* parent, const QImage &image, const QgsPoint &worldPos , const QString &layerId )
 {
   QMap<void*, QgsBillBoardItem*>::iterator it = mItems.find( parent );

diff --git a/src/core/qgsbillboardregistry.h b/src/core/qgsbillboardregistry.h
@@ -24,36 +24,51 @@
 
 class QgsMapCanvasItem;
 
-/** Billboard items stored in the QgsBillBoardRegistry */
+/** \ingroup core
+ * \class QgsBillBoardItem
+ * \note added in QGIS 2.16
+ * A billboard item stored in the QgsBillBoardRegistry.
+ */
 class CORE_EXPORT QgsBillBoardItem
 {
   public:
-    QImage image; /* The image of the billboard */
-    QgsPoint worldPos; /* The WGS84 world position of the billboard */
-    QString layerId; /* The layer which the image is part of, if any */
+    //! The image of the billboard
+    QImage image;
+    //! The WGS84 world position of the billboard
+    QgsPoint worldPos;
+    //! The layer which the image is part of, if any
+    QString layerId;
 };
 
-/**
+/** \ingroup core
+ * \class QgsBillBoardRegistry
+ * \note added in QGIS 2.16
  * @brief The QgsBillBoardRegistry class stores images which should
  * be displayed as billboards in the globe plugin.
  * Map canvas items and layers may decide to add items which should
  * be drawn as billboards in the globe.
  *
- * Retreive the instance pointer to a QgsBillBoardRegistry for a
+ * Retrieve the instance pointer to a QgsBillBoardRegistry for a
  * project via QgsProject::instance()->billboardRegistry().
  */
 class CORE_EXPORT QgsBillBoardRegistry : public QObject
 {
     Q_OBJECT
   public:
+
+    ~QgsBillBoardRegistry();
+
     /**
-     * @brief Adds a billboard to the registry
-     * @param parent The parent (i.e. a QgsMapLayer or a QgsMapCanvasItem) which is creating the billboard
+     * @brief Adds a billboard to the registry.
+     * @param parent The parent (i.e. a QgsMapLayer or a QgsMapCanvasItem) which is creating the billboard.
+     * Each parent can only have a single billboard - if a billboard for the parent already exists, it will
+     * be updated to match to new image and settings.
      * @param image The billboard image
      * @param worldPos The geo position of the image, in WGS84
      * @param layerId The id of the layer to which the item belongs, if any
      */
     void addItem( void* parent, const QImage& image, const QgsPoint& worldPos, const QString& layerId = QString() );
+
     /**
      * @brief Removes all billboards which were created by the specified parent
      * @param parent The parent
@@ -74,7 +89,7 @@ class CORE_EXPORT QgsBillBoardRegistry : public QObject
 
   private:
     friend class QgsProject; // Only QgsProject is allowed to construct this class
-    QgsBillBoardRegistry( QObject* parent = 0 ) : QObject( parent ) {}
+    QgsBillBoardRegistry( QObject* parent = nullptr ) : QObject( parent ) {}
 
     QMap<void*, QgsBillBoardItem*> mItems;
 };

diff --git a/src/core/qgsmapsettings.h b/src/core/qgsmapsettings.h
@@ -114,9 +114,18 @@ class CORE_EXPORT QgsMapSettings
     //! @note added in 2.8
     void setLayerStyleOverrides( const QMap<QString, QString>& overrides );
 
-    //! Get custom rendering flags, separated by ';'. Layers might honour these to alter their rendering.
-    const QString& customRenderFlags() const { return mCustomRenderFlags; }
-    //! Set custom rendering flags, separated by ';'. Layers might honour these to alter their rendering.
+    /** Get custom rendering flags. Layers might honour these to alter their rendering.
+     *  @returns custom flags strings, separated by ';'
+     * @note added in QGIS 2.16
+     * @see setCustomRenderFlags()
+     */
+    QString customRenderFlags() const { return mCustomRenderFlags; }
+
+    /** Sets the custom rendering flags. Layers might honour these to alter their rendering.
+     * @param customRenderFlags custom flags strings, separated by ';'
+     * @note added in QGIS 2.16
+     * @see customRenderFlags()
+     */
     void setCustomRenderFlags( const QString& customRenderFlags ) { mCustomRenderFlags = customRenderFlags; }
 
     //! sets whether to use projections for this layer set

diff --git a/src/core/qgsproject.cpp b/src/core/qgsproject.cpp
@@ -381,6 +381,7 @@ QgsProject::~QgsProject()
   delete mBadLayerHandler;
   delete mRelationManager;
   delete mRootGroup;
+  delete mBillboardRegistry;
 
   // note that QScopedPointer automatically deletes imp_ when it's destroyed
 } // QgsProject dtor

diff --git a/src/gui/CMakeLists.txt b/src/gui/CMakeLists.txt
@@ -613,6 +613,7 @@ SET(QGIS_GUI_HDRS
   qgsmapcanvassnapper.h
   qgsmapcanvassnappingutils.h
   qgsmapcanvastracer.h
+  qgsmaplayerpropertiesfactory.h
   qgsmapmouseevent.h
   qgsmaptip.h
   qgsnumericsortlistviewitem.h

diff --git a/src/gui/qgisinterface.h b/src/gui/qgisinterface.h
@@ -329,10 +329,16 @@ class GUI_EXPORT QgisInterface : public QObject
     /** Unregister a previously registered action. (e.g. when plugin is going to be unloaded) */
     virtual bool unregisterMainWindowAction( QAction* action ) = 0;
 
-    /** Register a new tab in the vector layer properties dialog */
+    /** Register a new tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see unregisterMapLayerPropertiesFactory()
+    */
     virtual void registerMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) = 0;
 
-    /** Unregister a previously registered tab in the layer properties dialog */
+    /** Unregister a previously registered tab in the vector layer properties dialog.
+     * @note added in QGIS 2.16
+     * @see registerMapLayerPropertiesFactory()
+    */
     virtual void unregisterMapLayerPropertiesFactory( QgsMapLayerPropertiesFactory* factory ) = 0;
 
     // @todo is this deprecated in favour of QgsContextHelp?

diff --git a/src/gui/qgsmaplayerpropertiesfactory.h b/src/gui/qgsmaplayerpropertiesfactory.h
@@ -20,8 +20,10 @@
 
 #include "qgsvectorlayerpropertiespage.h"
 
-/**
- * @brief Factory class for creating custom map layer property pages
+/** \ingroup gui
+ * \class QgsMapLayerPropertiesFactory
+ * \note added in QGIS 2.16
+ * Factory class for creating custom map layer property pages
  */
 class GUI_EXPORT QgsMapLayerPropertiesFactory
 {

diff --git a/src/gui/qgsvectorlayerpropertiespage.cpp b/src/gui/qgsvectorlayerpropertiespage.cpp
@@ -15,8 +15,8 @@
 
 #include "qgsvectorlayerpropertiespage.h"
 
-QgsVectorLayerPropertiesPage::QgsVectorLayerPropertiesPage( QWidget *parent ) :
-    QWidget( parent )
+QgsVectorLayerPropertiesPage::QgsVectorLayerPropertiesPage( QWidget *parent )
+    : QWidget( parent )
 {
 }
 
diff --git a/src/gui/qgsvectorlayerpropertiespage.h b/src/gui/qgsvectorlayerpropertiespage.h
@@ -20,15 +20,20 @@
 
 class QgsVectorLayer;
 
-/**
- * @brief Base class for custom vector layer property pages
+/** \ingroup gui
+ * \class QgsVectorLayerPropertiesPage
+ * \note added in QGIS 2.16
+ * Base class for custom vector layer property pages
  */
 class GUI_EXPORT QgsVectorLayerPropertiesPage : public QWidget
 {
     Q_OBJECT
   public:
-    /** Constructor */
-    explicit QgsVectorLayerPropertiesPage( QWidget *parent = 0 );
+
+    /** Constructor for QgsVectorLayerPropertiesPage.
+     * @param parent parent widget
+    */
+    explicit QgsVectorLayerPropertiesPage( QWidget *parent = nullptr );
 
   public slots:
     /** Apply changes */